From aa9abeb86d9b067e5f95373b0cff609c7b634477 Mon Sep 17 00:00:00 2001 From: Fernando de Oliveira <5161098+fedeoliv@users.noreply.github.com> Date: Fri, 16 Oct 2026 17:39:19 -0400 Subject: [PATCH] chore(specs): encourage focused diagrams (#35) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 40bf5936-fdf2-408a-afe7-dd07b66ed7da --- .github/instructions/specs.instructions.md | 1 + .github/plugins/devsquad/agents/devsquad.specify.agent.md | 2 ++ .../templates/.github/instructions/specs.instructions.md | 1 + .../devsquad/hooks/templates/docs/features/TEMPLATE.md | 8 ++++++++ CHANGELOG.md | 2 ++ docs/src/content/docs/agents/lifecycle.mdx | 1 + 6 files changed, 15 insertions(+) diff --git a/.github/instructions/specs.instructions.md b/.github/instructions/specs.instructions.md index 5cf6c78..ed1ceb5 100644 --- a/.github/instructions/specs.instructions.md +++ b/.github/instructions/specs.instructions.md @@ -8,6 +8,7 @@ When editing feature specs, follow these rules: - Focus on **WHAT** users need and **WHY**, never on HOW to implement. - Written for business stakeholders, not developers. +- When a visual clarifies a user flow, state transition, conceptual data relationship, or system boundary, consult `diagram-design` and include a focused diagram near the relevant text. Prefer Mermaid for simple diagrams. Keep business specs technology-independent, omit diagrams that add no clarity, and use the platform-appropriate rendering format. - Every user story must be prioritized (P1, P2, P3) and independently testable. - The spec must describe a vertical slice (tracer bullet) that (1) has at least one conformance case that runs end-to-end, not a unit-level check; (2) can be demoed, called, or observed by someone outside the implementing team without referring to a future spec; (3) touches every layer the feature requires (data, logic, and surface). Each slice cuts through all integration layers, not a horizontal slice of one layer. Sizing is handled by `complexity-analysis` during decomposition, not in the spec — if a slice is too large to estimate, decomposition will flag it. - Resist specifying P2/P3 in detail until P1 is implemented and reviewed. Write a short placeholder for later priorities (intent + assumptions) and expand when the slice becomes current. diff --git a/.github/plugins/devsquad/agents/devsquad.specify.agent.md b/.github/plugins/devsquad/agents/devsquad.specify.agent.md index 3d677cc..f2e6c67 100644 --- a/.github/plugins/devsquad/agents/devsquad.specify.agent.md +++ b/.github/plugins/devsquad/agents/devsquad.specify.agent.md @@ -34,6 +34,7 @@ Without `[CONDUCTOR]` → normal interactive flow. ## Style Guide - Skill `documentation-style` (text formatting) +- Skill `diagram-design` (focused diagrams that clarify behavior or conceptual relationships without prescribing implementation) - Skill `reasoning` (reasoning log and handoff envelope) - Skill `work-item-creation` (if creating feature on the board) - Skill `domain-glossary` (validate spec terms against glossary, if glossary exists) @@ -196,6 +197,7 @@ Given this feature description, do the following: No limit on DEFERRED markers. Unlike NEEDS CLARIFICATION, DEFERRED items do not block sprint readiness. 4. Fill in User Scenarios and Tests section If no clear user flow: ERROR "Unable to determine user scenarios" + When flows, state changes, conceptual entity relationships, or system boundaries are easier to understand visually, consult `diagram-design` and add a focused diagram beside the relevant section. Prefer Mermaid for simple diagrams and apply the platform rendering rules. Keep the diagram at the business level without technology choices or internal implementation details. Omit it when prose or a small table is clearer. 5. Generate Functional Requirements Each requirement must be testable Use reasonable defaults for unspecified details (document assumptions in the Assumptions section) diff --git a/.github/plugins/devsquad/hooks/templates/.github/instructions/specs.instructions.md b/.github/plugins/devsquad/hooks/templates/.github/instructions/specs.instructions.md index fe64407..5e964b3 100644 --- a/.github/plugins/devsquad/hooks/templates/.github/instructions/specs.instructions.md +++ b/.github/plugins/devsquad/hooks/templates/.github/instructions/specs.instructions.md @@ -8,6 +8,7 @@ When editing feature specs, follow these rules: - Focus on **WHAT** users need and **WHY**, never on HOW to implement. - Written for business stakeholders, not developers. +- When a visual clarifies a user flow, state transition, conceptual data relationship, or system boundary, consult `diagram-design` and include a focused diagram near the relevant text. Prefer Mermaid for simple diagrams. Keep business specs technology-independent, omit diagrams that add no clarity, and use the platform-appropriate rendering format. - Every user story must be prioritized (P1, P2, P3) and independently testable. - The spec must describe a vertical slice (tracer bullet) that (1) has at least one conformance case that runs end-to-end, not a unit-level check; (2) can be demoed, called, or observed by someone outside the implementing team without referring to a future spec; (3) touches every layer the feature requires (data, logic, and surface). Each slice cuts through all integration layers, not a horizontal slice of one layer. Sizing is handled by `complexity-analysis` during decomposition, not in the spec — if a slice is too large to estimate, decomposition will flag it. - Every functional requirement must be testable and unambiguous. Vague terms like "fast", "easy", "intuitive" must be quantified. diff --git a/.github/plugins/devsquad/hooks/templates/docs/features/TEMPLATE.md b/.github/plugins/devsquad/hooks/templates/docs/features/TEMPLATE.md index ec13ad6..c661801 100644 --- a/.github/plugins/devsquad/hooks/templates/docs/features/TEMPLATE.md +++ b/.github/plugins/devsquad/hooks/templates/docs/features/TEMPLATE.md @@ -112,6 +112,14 @@ For features whose Change type is not "new surface", recovery semantics belong i ## User Scenarios & Tests *(required)* + +