doorstop-usage

name

doorstop-usage

description

How to use Doorstop for requirements traceability in Agent V. Use this skill whenever you need to run Doorstop commands (create, add, link, publish, review), understand the document tree structure, create or edit YAML requirement items, fix Doorstop validation warnings, or understand parent-child relationships between documents. Also use when you see Doorstop prefixes like STR, SYSRS, SWRS, SWARCH, SWDD, UT, SWIT, SYIT, SWQT, SYQT, or when dealing with traceability links, suspect links, or review hashes.

Doorstop Usage in Agent V

Document Tree

Agent V uses 11 Doorstop documents. Each stores YAML items under reqs/<PREFIX>/. Parent-child relationships enforce traceability — a child item must link to at least one parent item.

STR (Stakeholder Requirements)        <- root, no parent
└── SYSRS (System Requirements)       <- parent: STR
    ├── SYQT (System Qualification Tests)   <- parent: SYSRS
    ├── SYSARCH (System Architecture)       <- parent: SYSRS
    │   └── SYIT (System Integration Tests) <- parent: SYSARCH
    └── SWRS (Software Requirements)        <- parent: SYSRS
        ├── SWQT (SW Qualification Tests)   <- parent: SWRS
        └── SWARCH (SW Architecture)        <- parent: SWRS
            ├── SWIT (SW Integration Tests) <- parent: SWARCH
            └── SWDD (SW Detailed Design)   <- parent: SWARCH
                └── UT (Unit Tests)         <- parent: SWDD

Important: SYSARCH and SWARCH items are traceability anchors — lightweight index entries pointing to the real architecture documents in artifacts/. They enable automated link checking across the full V-model chain.

Essential Commands

# Validate entire tree (run this before writing GATE_PASSED)
uv run doorstop

# Add a new item to a document
uv run doorstop add SWRS          # Creates SWRS001, SWRS002, etc.

# Link a child item to a parent item
uv run doorstop link SWRS001 SYSRS001

# Cross-link (non-parent link, e.g., SWRS to SYSARCH per SWE.1.BP6)
uv run doorstop link SWRS001 SYSARCH001

# Mark all items as reviewed (clears suspect link warnings)
uv run doorstop review all

# Publish all documents to HTML/Markdown
uv run doorstop publish all reports/

Key Pitfalls (Summary)

• ref field: Leave ref: '' unless pointing to a real file path on disk. Text strings cause validation errors.
• Suspect links: Normal after parent modification. Fix with uv run doorstop review all.
• Link direction: doorstop link CHILD PARENT — child links TO parent, not the reverse.
• Empty documents: Warnings about empty docs are expected during pipeline execution.

Detailed References

• For YAML item format and custom attributes by document type, read references/yaml-format.md.
• For detailed pitfalls (ref field, suspect links, review hashes, empty documents, link direction), read references/pitfalls.md.