ai-unified-process/aiup-core
AI Unified Process core - stack-agnostic requirements, entity model, and use cases
92
92%
Does it follow best practices?
Impact
92%
1.26xAverage score across 16 eval scenarios
Low
Low-risk findings worth noting
lint-codes.mdskills/spec-review/references/
Lint Codes
scripts/spec_lint.py prints one line per finding:
docs/use_cases/UC-004-book-room.md:12: ERROR DANGLING_REF [UC-004]: requirement FR-019 is not in requirements.mdThe format is path:line: SEVERITY CODE [element]: message. Line 0 means the finding concerns the whole file.
The exit code is 0 when the run is clean, 1 on any ERROR (with --strict, also on any WARN), and 2 on usage
errors.
Cross-file codes
| Severity | Code | Meaning | Fix with |
|---|---|---|---|
| ERROR | SPEC_MISSING | A use case in use_cases.puml has no use_cases/UC-XXX-*.md | /use-case-spec |
| ERROR | NOT_IN_DIAGRAM | A specification (not Obsolete) whose use case is not in use_cases.puml | /use-case-diagram |
| ERROR | DUPLICATE_ID | A UC, TC, BP, FR, NFR, or C id, or an entity heading, is used twice | the owning skill |
| ERROR | DANGLING_REF | An FR, NFR, or C id in **Requirements:**, a UC-xxx BR-yyy citation, a UC link in a test case, or a **Process:** link or BP-XXX id points to nothing | the owning skill |
| ERROR | BPMN_UNMAPPED | A BPMN activity whose name carries no known use case id and matches no use case title | /use-case-spec |
| ERROR | BPMN_INVALID | A .bpmn file that cannot be parsed | the modeling tool |
| ERROR | BP_ID_MISMATCH | A process model whose BP-XXX process id and file name prefix (BP-XXX-<name>.bpmn) differ | /business-process |
| WARN | ACTOR_MISMATCH | A primary or secondary actor of a specification that use_cases.puml does not connect to the use case (or does not declare), or an actor the diagram connects that the specification does not list. Actors are compared by name, primary and secondary together; an actor inherits its parent's links (`Manager -- | > Clerk`); a use case the diagram connects to no actor is skipped |
| WARN | FR_UNCOVERED | An FR (not Rejected or Deferred) that no active use case lists in **Requirements:** | /use-case-spec |
| WARN | REQ_STATUS_DRIFT | A requirement's progress status (Open, In Progress, Implemented, Verified) differs from the one the **Status:** of its linking use cases gives it | /requirements |
| WARN | BR_DUPLICATE | Two use cases carry the same rule text; keep it in one and cite it as UC-xxx BR-yyy | /use-case-spec |
| WARN | WEAK_WORD | A vague or optional word ("fast", "appropriate", "etc.", "and/or", "should", "ggf.", …) | the owning skill |
| WARN | GLOSSARY_AVOIDED_TERM | A synonym that glossary.md lists in its Avoid column | the owning skill |
| WARN | GLOSSARY_DUPLICATE | A term defined twice in glossary.md | /requirements |
| INFO | NO_TRACEABILITY | No use case has a **Requirements:** field, so FR coverage is not checked | /use-case-spec |
| INFO | BP_NO_ID | A process model without a BP-XXX process id (e.g. drawn before /business-process) | /business-process |
| INFO | REQ_UNCOVERED | An NFR or C (not Rejected or Deferred) that no use case lists; fine when it applies to the whole system | /use-case-spec |
| INFO | UC_UNUSED_BY_TC | Test cases exist, but none of them includes this use case | /test-case |
| INFO | BASELINE_STALE | A baseline entry that no longer matches any finding; refresh with --update-baseline | — |
| INFO | VALIDATOR_MISSING, BPMN_PARSER_MISSING | A sibling skill is not installed, so its checks were skipped | install aiup-core |
Per-file codes
spec_lint.py runs validate_use_case.py from the use-case-spec skill over every use case and passes its findings
through unchanged: ERROR means the document does not parse (TITLE_MISSING, OVERVIEW_MISSING, FIELD_MISSING,
STATUS_INVALID, FLOW_INCOMPLETE, UNEXPECTED_CONTENT), and WARN means a rule of the use-case-spec skill is
broken (SECTION_MISSING, NUMBERING, NO_ALTERNATIVE_FLOWS, TRIGGER_STEP_REF, FLOW_TERMINATION,
POSTCONDITIONS_EMPTY, RULE_LABEL_MISSING, RULE_NUMBERING, TECHNICAL_TERM, UC_TRIGGER_EMPTY,
UC_TRIGGER_STEP_REF, UC_TRIGGER_IS_PRECONDITION, …). Fix them with /use-case-spec.
Options
| Option | Effect |
|---|---|
--docs DIR | documentation folder (default docs) |
--only UC-XXX / TC-XXX / BP-XXX | report only findings about this element |
--strict | fail on warnings too |
--format json | print {"findings": [...], "summary": {...}} |
--baseline FILE | use this baseline (default DIR/.spec-lint-baseline.json when it exists) |
--no-baseline | report every finding |
--update-baseline | accept all current ERROR and WARN findings into the baseline, then exit 0 |
--self-test | run the built-in fixtures |
A baseline entry is a fingerprint of code, file, element, and message — not the line number — so it survives edits elsewhere in the file.