doc-req

仓库: vladm3105/aidoc-flow-framework
安装量: 49
排名: #15253

安装

npx skills add https://github.com/vladm3105/aidoc-flow-framework --skill doc-req

doc-req Purpose

Create Atomic Requirements (REQ) documents - Layer 7 artifact in the SDD workflow that decomposes system requirements into atomic, implementation-ready requirements using REQ v3.0 format.

Layer: 7

Upstream: BRD (Layer 1), PRD (Layer 2), EARS (Layer 3), BDD (Layer 4), ADR (Layer 5), SYS (Layer 6)

Downstream Artifacts: IMPL (Layer 8), CTR (Layer 9), SPEC (Layer 10), Code (Layer 13)

Prerequisites Upstream Artifact Verification (CRITICAL)

Before creating this document, you MUST:

List existing upstream artifacts:

ls docs/BRD/ docs/PRD/ docs/EARS/ docs/BDD/ docs/ADR/ docs/SYS/ docs/REQ/ 2>/dev/null

Reference only existing documents in traceability tags

Use null only when upstream artifact type genuinely doesn't exist

NEVER use placeholders like BRD-XXX or TBD

Do NOT create missing upstream artifacts - skip functionality instead

Before creating REQ, read:

Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md Upstream SYS: Read system requirements driving this REQ Template: ai_dev_flow/REQ/REQ-TEMPLATE.md Creation Rules: ai_dev_flow/REQ/REQ_CREATION_RULES.md Validation Rules: ai_dev_flow/REQ/REQ_VALIDATION_RULES.md Validation Script: ./ai_dev_flow/scripts/validate_req_template.sh When to Use This Skill

Use doc-req when:

Have completed BRD through SYS (Layers 1-6) Need to decompose system requirements into atomic units Preparing for implementation (Layer 8+) Achieving >=90% SPEC-readiness score You are at Layer 7 of the SDD workflow Reserved ID Exemption (REQ-00_*)

Scope: Documents with reserved ID 000 are FULLY EXEMPT from validation.

Pattern: REQ-00_*.md

Document Types:

Index documents (REQ-00_index.md) Traceability matrix templates (REQ-00_TRACEABILITY_MATRIX-TEMPLATE.md) Glossaries, registries, checklists

Rationale: Reserved ID 000 documents are framework infrastructure, not project artifacts requiring traceability or quality gates.

Validation Behavior: Skip all checks when filename matches REQ-00_* pattern.

REQ-Specific Guidance 1. REQ v3.0 Format (12 Required Sections)

CRITICAL: REQ v3.0 expanded from 7 to 12 sections

Document Control (MANDATORY - First section before all numbered sections)

Core Sections:

Description: Atomic requirement + SHALL/SHOULD/MAY language + context + scenario Functional Requirements: Core capabilities + business rules Interface Specifications: Protocol/ABC definitions + DTOs + REST endpoints Data Schemas: JSON Schema + Pydantic models + Database schema Error Handling Specifications: Exception catalog + error response schema + circuit breaker config Configuration Specifications: YAML schema + environment variables + validation Quality Attributes: Performance targets (p50/p95/p99) + reliability/security/scalability Implementation Guidance: Algorithms/patterns + concurrency/async + dependency injection Acceptance Criteria: >=15 measurable criteria covering functional/error/quality/data/integration Verification Methods: BDD scenarios + unit/integration/contract/performance tests Traceability: Section 7 format with cumulative tags (6 required) Change History: Version control table 2. Document Control Requirements (11 Mandatory Fields) Field Format Example Status Approved/In Review/Draft Approved Version Semantic X.Y.Z 2.0.1 Date Created ISO 8601 2025-11-18 Last Updated ISO 8601 2025-11-19 Author Name/Role System Architect Priority Level (P-level) High (P2) Category Type Functional Source Document DOC-ID section X.Y.Z SYS-02 section 3.1.1 Verification Method Method type BDD + Integration Test Assigned Team Team name IB Integration Team SPEC-Ready Score Format with emoji >=90% (Target: >=90%) IMPL-Ready Score Format with emoji >=90% (Target: >=90%) Template Version Must be 3.0 3.0 3. Dual Readiness Scoring (SPEC-Ready + IMPL-Ready)

MANDATORY: Each REQ must calculate BOTH scores

SPEC-Ready Score Formula:

SPEC-Ready Score = (Completed Sections / 12) * 100%

IMPL-Ready Score: Measures readiness for implementation approach documentation

Quality Gate: Both scores >=90% required for layer transition

Status and Ready Score Mapping:

Ready Score Required Status

= 90% Approved 70-89% In Review < 70% Draft

Note: For REQ documents with dual scores, use the LOWER score to determine status.

Example:

Readiness Scores

SPEC-Ready Score: >=95% (Target: >=90%) IMPL-Ready Score: >=92% (Target: >=90%)

Section Status: - [x] 1. Description - [x] 2. Functional Requirements - [x] 3. Interface Specifications - [x] 4. Data Schemas - [x] 5. Error Handling Specifications - [x] 6. Configuration Specifications - [x] 7. Quality Attributes - [x] 8. Implementation Guidance - [x] 9. Acceptance Criteria - [x] 10. Verification Methods - [x] 11. Traceability - [ ] 12. Change History (In Progress)

Readiness: READY for SPEC/IMPL creation

  1. Element ID Format (MANDATORY)

Pattern: REQ.{DOC_NUM}.{ELEM_TYPE}.{SEQ} (4 segments, dot-separated)

Element Type Code Example Functional Requirement 01 REQ.02.01.01 Dependency 05 REQ.02.05.01 Acceptance Criteria 06 REQ.02.06.01 Atomic Requirement 27 REQ.02.27.01

REMOVED PATTERNS - Do NOT use:

AC-XXX - Use REQ.NN.06.SS FR-XXX - Use REQ.NN.01.SS R-XXX - Use REQ.NN.27.SS REQ-XXX - Use REQ.NN.27.SS

Reference: ID_NAMING_STANDARDS.md - Cross-Reference Link Format

  1. Atomic Requirement Principles Single Responsibility: Each REQ defines exactly one requirement Measurable: Acceptance criteria provide true/false outcomes Self-Contained: Understandable without external context SPEC-Ready: Contains ALL information for automated SPEC generation (>=90% completeness) Modal Language: SHALL (absolute), SHOULD (preferred), MAY (optional)
  2. Domain/Subdomain Organization

Location: REQ/{domain}/{subdomain}/ within project docs directory

Domains: api/ (external integrations), risk/ (risk management), data/ (data requirements), ml/ (ML requirements), auth/ (security), etc.

Format: REQ-NN_descriptive_slug.md

Example: REQ-risk-limits-01_position_validation.md

Tag Format Convention (By Design)

The SDD framework uses two distinct notation systems for cross-references:

Notation Format Artifacts Purpose Dash TYPE-NN ADR, SPEC, CTR Technical artifacts - references to files/documents Dot TYPE.NN.TT.SS BRD, PRD, EARS, BDD, SYS, REQ, IMPL, TASKS Hierarchical artifacts - references to elements inside documents

Key Distinction:

@adr: ADR-033 -> Points to the document ADR-033_risk_limit_enforcement.md @brd: BRD.17.01.03 -> Points to element 01.03 inside document BRD-017.md Cumulative Tagging Requirements

Layer 7 (REQ): Must include tags from Layers 1-6 (BRD, PRD, EARS, BDD, ADR, SYS)

Tag Count: 6 tags (@brd, @prd, @ears, @bdd, @adr, @sys)

Format:

Traceability

Required Tags (Cumulative Tagging Hierarchy - Layer 7): ```markdown @brd: BRD.01.01.03 @prd: PRD.01.07.02 @ears: EARS.01.25.01 @bdd: BDD.01.14.01 @adr: ADR-033, ADR-045 @sys: SYS.01.01.01, SYS.01.02.07

Upstream Sources:

BRD-01 PRD-01 EARS-01 BDD-01 ADR-033 SYS-01

Downstream Artifacts:

IMPL-NN (to be created) - Implementation approach CTR-NN (to be created) - Data contracts SPEC-NN (to be created) - Technical specifications

Element Type Codes for Tags: - EARS: Type 25 (formal requirement) - BDD: Type 14 (scenario) - SYS: Type 01 (functional), 02 (quality attribute), 26 (system req)

Threshold Registry Integration

Purpose: Prevent magic numbers by referencing centralized threshold registry.

When @threshold Tag is Required

Use @threshold for ALL quantitative values that are: - Business-critical (compliance limits, SLAs) - Configurable (timeout values, rate limits, retry policies) - Shared across documents (performance targets) - Quality attribute-related (p50/p95/p99 latencies, throughput limits) - Error handling configurations (circuit breaker, retry counts)

@threshold Tag Format

```markdown @threshold: PRD.NN.category.subcategory.key

Examples:

@threshold: PRD.035.perf.api.p95_latency @threshold: PRD.035.timeout.circuit_breaker.threshold @threshold: PRD.035.retry.max_attempts @threshold: PRD.035.limit.api.requests_per_second REQ-Specific Threshold Categories Category REQ Usage Example Key perf. Performance acceptance criteria perf.api.p95_latency timeout. Circuit breaker, connection configs timeout.circuit_breaker.reset retry. Retry policy configurations retry.max_attempts limit. Rate limits, resource limits limit.api.requests_per_second resource.* Memory, CPU constraints resource.memory.max_heap Magic Number Detection

Invalid (hardcoded values):

p95 response time: 200ms max_retries: 3 rate_limit: 100 req/s

Valid (registry references):

p95 response time: @threshold: PRD.NN.perf.api.p95_latency max_retries: @threshold: PRD.NN.retry.max_attempts rate_limit: @threshold: PRD.NN.limit.api.requests_per_second Upstream/Downstream Artifacts

Upstream Sources:

BRD (Layer 1) - Business requirements PRD (Layer 2) - Product features EARS (Layer 3) - Formal requirements BDD (Layer 4) - Test scenarios ADR (Layer 5) - Architecture decisions SYS (Layer 6) - System requirements (PRIMARY SOURCE)

Downstream Artifacts:

IMPL (Layer 8) - Implementation approach (optional) CTR (Layer 9) - Data contracts (optional) SPEC (Layer 10) - Technical specifications Code (Layer 13) - Implementation

Same-Type Document Relationships (conditional):

@related-req: REQ-NN - REQs sharing domain context @depends-req: REQ-NN - REQ that must be implemented first Creation Process Step 1: Read Upstream Artifacts

Especially focus on SYS (Layer 6) - system requirements to decompose.

Step 2: Reserve ID Number

Check ai_dev_flow/REQ/ for next available ID number.

ID Numbering Convention: Start with 2 digits and expand only as needed.

✅ Correct: REQ-01, REQ-99, REQ-102 ❌ Incorrect: REQ-001, REQ-009 (extra leading zero not required)

Domain-based naming: REQ-domain-subdomain-NN

Step 3: Create REQ File

Location Options:

Flat: docs/REQ/REQ-{NN}{slug}.md Domain-based: docs/REQ/{domain}/REQ-NN.md Subdomain: docs/REQ/{domain}/{subdomain}/REQ-NN_{slug}.md

On-Demand Folder Creation: Before saving the document, create the target directory:

Create target directory if it doesn't exist

mkdir -p docs/REQ/{domain}/ # For domain-based structure

OR

mkdir -p docs/REQ/{domain}/{subdomain}/ # For subdomain structure

Domain Selection: Use domain from project configuration or upstream SYS context:

Financial: risk/, trading/, collection/, compliance/, ml/ SaaS: tenant/, subscription/, billing/, workspace/ Generic: api/, auth/, data/, core/, integration/

Section Files: For large requirements (>50KB), use Section Files format: REQ-NN.S_section_title.md (S = section number).

Step 4: Fill Document Control Section

Complete metadata with all 11 required fields plus Document Revision History table.

Step 5: Complete All 12 Required Sections

Critical: REQ v3.0 requires all 12 sections for >=90% SPEC-readiness

Description: Atomic requirement + SHALL/SHOULD/MAY language Functional Requirements: Core capabilities + business rules Interface Specifications: APIs, endpoints, contracts, Protocol/ABC class Data Schemas: Models, validation, constraints, Pydantic/dataclass Error Handling Specifications: Error codes, recovery, exception definitions Configuration Specifications: Settings, feature flags, YAML config Quality Attributes: Performance, security, scalability with thresholds Implementation Guidance: Technical approach, patterns Acceptance Criteria: >=15 measurable criteria Verification Methods: BDD scenarios, tests Traceability: Cumulative tags (6 tags) Change History: Version control table Step 6: Calculate Readiness Scores

Count completed sections and calculate both SPEC-Ready and IMPL-Ready percentages.

Quality Gate: Both scores must achieve >=90%

Step 7: Add Cumulative Tags

Include all 6 upstream tags (@brd through @sys).

Step 8: Create/Update Traceability Matrix

MANDATORY: Update ai_dev_flow/REQ/REQ-00_TRACEABILITY_MATRIX-TEMPLATE.md

Step 9: Validate REQ ./ai_dev_flow/scripts/validate_req_template.sh ai_dev_flow/REQ/REQ-NN_*.md

python ai_dev_flow/scripts/validate_tags_against_docs.py --artifact REQ-NN --expected-layers brd,prd,ears,bdd,adr,sys --strict

Step 10: Commit Changes

Commit REQ file and traceability matrix.

Validation Validation Checks (20 Total) Check Description Type CHECK 1 Required 12 sections Error CHECK 2 Document Control (11 fields) Error CHECK 3 Traceability structure Error/Warning CHECK 4 Legacy (deprecated) Info CHECK 5 Version format (X.Y.Z) Error CHECK 6 Date format (ISO 8601) Error CHECK 7 Priority format (P1-P4) Warning CHECK 8 Source document format Warning CHECK 9 SPEC-Ready Score Error/Warning CHECK 10 Template Version (3.0) Error CHECK 11 Change History Error/Warning CHECK 12 Filename/ID format Error CHECK 13 Resource tag (Template 2.0) Error CHECK 14 Cumulative tagging (6 tags) Error CHECK 15 Complete upstream chain Error CHECK 16 Link resolution Error/Warning CHECK 17 Traceability matrix Warning CHECK 18 SPEC-Ready content Warning CHECK 19 IMPL-Ready Score Error CHECK 20 Element ID format compliance Error Validation Tiers Tier Type Exit Code Description Tier 1 Errors 1 Blocking - must fix before commit Tier 2 Warnings 0 Quality issues - recommended to fix Tier 3 Info 0 Informational - no action required Automated Validation

Validate single file

./scripts/validate_req_template.sh docs/REQ/REQ-NN_slug.md

Validate all REQ files

find docs/REQ -name "REQ-*.md" -exec ./scripts/validate_req_template.sh {} \;

Cumulative tagging validation

python ai_dev_flow/scripts/validate_tags_against_docs.py \ --artifact REQ-NN \ --expected-layers brd,prd,ears,bdd,adr,sys \ --strict

Manual Checklist Document Control section at top with 11 required fields All 12 required sections completed SPEC-Ready Score >=90% IMPL-Ready Score >=90% Template Version = 3.0 Section 3: Interface Specifications with Protocol/ABC class Section 4: Data Schemas with Pydantic/dataclass models Section 5: Error Handling with exception definitions Section 6: Configuration with YAML schema Section 7: Quality Attributes with @threshold references Section 9: >=15 acceptance criteria Cumulative tags: @brd through @sys (6 tags) included Each requirement atomic (single responsibility) Acceptance criteria testable and measurable Traceability matrix updated Diagram Standards

All diagrams MUST use Mermaid syntax. Text-based diagrams (ASCII art, box drawings) are prohibited. See: ai_dev_flow/DIAGRAM_STANDARDS.md and mermaid-gen skill.

Common Pitfalls Incomplete sections: All 12 sections mandatory for SPEC-readiness Missing new sections: Sections 3-7 are new in v3.0 - don't skip them Low readiness scores: Both SPEC-Ready and IMPL-Ready must achieve >=90% Non-atomic requirements: Each REQ must be single, testable unit Missing cumulative tags: Layer 7 must include all 6 upstream tags Vague acceptance criteria: Must be measurable and testable Hardcoded values: Use @threshold references, not magic numbers Legacy element IDs: Use REQ.NN.TT.SS format, not AC-XXX or FR-XXX Status/score mismatch: Status must match the LOWER of the two scores Post-Creation Validation (MANDATORY - NO CONFIRMATION)

CRITICAL: Execute this validation loop IMMEDIATELY after document creation.

Automatic Validation Loop LOOP: 1. Run: python scripts/validate_cross_document.py --document {doc_path} --auto-fix 2. IF errors fixed: GOTO LOOP (re-validate) 3. IF warnings fixed: GOTO LOOP (re-validate) 4. IF unfixable issues: Log for manual review, continue 5. IF clean: Mark VALIDATED, proceed

Validation Command

Per-document validation (Phase 1)

python ai_dev_flow/scripts/validate_cross_document.py --document docs/REQ/REQ-NN_slug.md --auto-fix

Layer validation (Phase 2) - run when all REQ documents complete

python ai_dev_flow/scripts/validate_cross_document.py --layer REQ --auto-fix

Layer-Specific Upstream Requirements This Layer Required Upstream Tags Count REQ (Layer 7) @brd, @prd, @ears, @bdd, @adr, @sys 6 tags Auto-Fix Actions (No Confirmation Required) Issue Fix Action Missing @brd/@prd/@ears/@bdd/@adr/@sys tag Add with upstream document reference Invalid tag format Correct to TYPE.NN.TT.SS (4-segment) or TYPE-NN format Broken link Recalculate path from current location Missing traceability section Insert from template Validation Codes Reference Code Description Severity XDOC-001 Referenced requirement ID not found ERROR XDOC-002 Missing cumulative tag ERROR XDOC-003 Upstream document not found ERROR XDOC-006 Tag format invalid ERROR XDOC-007 Gap in cumulative tag chain ERROR XDOC-009 Missing traceability section ERROR Quality Gate

Blocking: YES - Cannot proceed to IMPL/SPEC creation until Phase 1 validation passes with 0 errors.

Next Skill

After creating REQ, use:

doc-spec (or optionally doc-impl/doc-ctr first) - Create Technical Specifications (Layer 10)

The SPEC will:

Reference this REQ as upstream source Include all 7 upstream tags (@brd through @req) Use YAML format Define implementation contracts Achieve 100% implementation-readiness Reference Documents

REQ artifacts do not support REF documents. Reference documents are limited to BRD and ADR types only per the SDD framework.

For supplementary documentation needs, create:

BRD-REF: Business context and domain glossaries ADR-REF: Technical reference guides and architecture summaries Related Resources Template: ai_dev_flow/REQ/REQ-TEMPLATE.md (primary authority) REQ Creation Rules: ai_dev_flow/REQ/REQ_CREATION_RULES.md REQ Validation Rules: ai_dev_flow/REQ/REQ_VALIDATION_RULES.md REQ README: ai_dev_flow/REQ/README.md Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md

Section Templates (for documents >50KB):

Index template: ai_dev_flow/REQ/REQ-SECTION-0-TEMPLATE.md Content template: ai_dev_flow/REQ/REQ-SECTION-TEMPLATE.md Reference: ai_dev_flow/ID_NAMING_STANDARDS.md (Section-Based File Splitting) Quick Reference

REQ Purpose: Atomic, implementation-ready requirements

Layer: 7

Tags Required: @brd, @prd, @ears, @bdd, @adr, @sys (6 tags)

Format: REQ v3.0 (12 sections)

Quality Gate: SPEC-Ready Score >=90% AND IMPL-Ready Score >=90%

Element ID Format: REQ.NN.TT.SS

Functional Requirement = 01 Dependency = 05 Acceptance Criteria = 06 Atomic Requirement = 27

Removed Patterns: AC-XXX, FR-XXX, R-XXX, REQ-XXX

Document Control Fields: 11 required (+ Template Version = 3.0)

Status/Score Mapping: >=90% Approved, 70-89% In Review, <70% Draft

File Size Limits: >50KB use section files

Next: doc-spec (or optionally doc-impl/doc-ctr first)

← 返回排行榜