Skip to content

Add requirement granularity guidance to spec template, AGENTS.md section, and README#5

Draft
sansari with Copilot wants to merge 3 commits into
mainfrom
copilot/add-guidance-on-requirement-granularity
Draft

Add requirement granularity guidance to spec template, AGENTS.md section, and README#5
sansari with Copilot wants to merge 3 commits into
mainfrom
copilot/add-guidance-on-requirement-granularity

Conversation

Copilot AI commented Jul 22, 2026

Copy link
Copy Markdown

Agents drafting first-pass feature specs tend to over-decompose into 20+ MUST requirements, making the coverage/review cycle disproportionately heavy before a team has decided which behaviors are core product promises. This adds guidance nudging toward 3–8 workflow-level requirements per feature.

Changes

  • specs/REQ-010-granularity-guidance.md — new spec formalizing the granularity guidance requirements (REQ-010.1–3)

  • src/init.tsAGENTS_MD_SECTION — new "Requirement granularity" paragraph with:

    • 3–8 MUST recommendation with workflow-level vs. implementation-step contrast
    • Spec sizing smells: >10 MUSTs before tests, requirements restating internal steps, "MUST cover"/"MUST test" anti-patterns
  • src/init.tsSPEC_TEMPLATE — restructured from a generic single section to four explicit sections:

    ### REQ-001.1: Core workflows          ← MUST requirements for user workflows
    ### REQ-001.2: Safety and compatibility invariants
    ### REQ-001.3: Manual acceptance criteria   ← [manual]-tagged
    ## Notes and non-goals                ← prose, outside Requirements block
  • README.md — new ## Requirement granularity section with guidance, good/bad examples, sizing smells checklist, and starter spec structure

  • tests/granularity.test.ts — four tests covering REQ-010; each assertion verified by fresh-context reviewers to be genuinely falsifiable (e.g., REQ-010.2.1 extracts and checks that the Core workflows section contains a MUST, not just that the heading exists)

Copilot AI changed the title [WIP] Add guidance on manageable requirement granularity Add requirement granularity guidance to spec template, AGENTS.md section, and README Jul 22, 2026
Copilot AI requested a review from sansari July 22, 2026 18:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add guidance on manageable requirement granularity

2 participants