From 0188f5e3d1b11b1a0e4af459b1a8767d326e6115 Mon Sep 17 00:00:00 2001 From: Fernando de Oliveira <5161098+fedeoliv@users.noreply.github.com> Date: Fri, 16 Oct 2026 16:59:58 -0400 Subject: [PATCH] chore(authoring): favor readable names over invented IDs (#37) Remove sequential task and story prefixes from generated board titles and establish scoped naming guidance without breaking existing spec identifiers or references. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 40bf5936-fdf2-408a-afe7-dd07b66ed7da --- .github/copilot-instructions.md | 1 + .../documentation-style.instructions.md | 1 + .../devsquad/agents/devsquad.decompose.agent.md | 2 +- .../hooks/templates/.github/copilot-instructions.md | 1 + .../documentation-style.instructions.md | 1 + .../devsquad/skills/documentation-style/SKILL.md | 8 ++++++++ .../skills/quality-gate/references/rubrica-tasks.md | 1 + .../devsquad/skills/work-item-creation/SKILL.md | 13 ++++++++++++- CHANGELOG.md | 3 +++ docs/src/content/docs/skills/quality.mdx | 7 +++++++ 10 files changed, 36 insertions(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 149f167..586ea5e 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -87,6 +87,7 @@ When editing or creating markdown documents: - No contrastive framing ("not just X, it's Y", "goes beyond", "more than just"). Describe directly. - No rhetorical questions followed by obvious answers. State the assertion directly. - Prefer lists and tables over long paragraphs. +- Prefer descriptive names and links over invented identifiers. Follow the `documentation-style` skill for exceptions required by artifact-specific rules and for preserving existing references. --- diff --git a/.github/instructions/documentation-style.instructions.md b/.github/instructions/documentation-style.instructions.md index 13fe192..7702932 100644 --- a/.github/instructions/documentation-style.instructions.md +++ b/.github/instructions/documentation-style.instructions.md @@ -16,4 +16,5 @@ When editing markdown documentation, follow these formatting rules: - Do not use promotional language: "it's not just X, it's Y", "goes beyond...", "more than just...". Describe directly. - Do not use rhetorical questions followed by obvious answers. State the assertion directly. - Prefer lists and tables over long paragraphs. +- Prefer descriptive names and links over invented identifiers. Follow the `documentation-style` skill for exceptions required by artifact-specific rules and for preserving existing references. - For diagrams (design, review, Mermaid platform rendering, tool selection), follow the `diagram-design` skill. diff --git a/.github/plugins/devsquad/agents/devsquad.decompose.agent.md b/.github/plugins/devsquad/agents/devsquad.decompose.agent.md index ba8406b..d134e72 100644 --- a/.github/plugins/devsquad/agents/devsquad.decompose.agent.md +++ b/.github/plugins/devsquad/agents/devsquad.decompose.agent.md @@ -112,7 +112,7 @@ Consider the input above before proceeding (if not empty). **Before saving and creating work items**, present the Reasoning Log in the format from the `reasoning` skill. Wait for confirmation before creating work items. -8. **Create Work Items**: Invoke the `work-item-creation` skill according to the chosen platform. +8. **Create Work Items**: Invoke the `work-item-creation` skill according to the chosen platform. Validate every outgoing title against its Title rules before creating GitHub or Azure DevOps items. Use the descriptive title without local task or story numbering, retaining the required feature prefix and board hierarchy and dependency links. 9. **Consistency Validation**: diff --git a/.github/plugins/devsquad/hooks/templates/.github/copilot-instructions.md b/.github/plugins/devsquad/hooks/templates/.github/copilot-instructions.md index b751686..0426ac8 100644 --- a/.github/plugins/devsquad/hooks/templates/.github/copilot-instructions.md +++ b/.github/plugins/devsquad/hooks/templates/.github/copilot-instructions.md @@ -94,3 +94,4 @@ When editing or creating markdown documents: - No contrastive framing ("not just X, it's Y", "goes beyond", "more than just"). Describe directly. - No rhetorical questions followed by obvious answers. State the assertion directly. - Prefer lists and tables over long paragraphs. +- Prefer descriptive names and links over invented identifiers. Follow the `documentation-style` skill for exceptions required by artifact-specific rules and for preserving existing references. diff --git a/.github/plugins/devsquad/hooks/templates/.github/instructions/documentation-style.instructions.md b/.github/plugins/devsquad/hooks/templates/.github/instructions/documentation-style.instructions.md index 4d55212..82f4078 100644 --- a/.github/plugins/devsquad/hooks/templates/.github/instructions/documentation-style.instructions.md +++ b/.github/plugins/devsquad/hooks/templates/.github/instructions/documentation-style.instructions.md @@ -16,6 +16,7 @@ When editing markdown documentation, follow these formatting rules: - Do not use promotional language: "it's not just X, it's Y", "goes beyond...", "more than just...". Describe directly. - Do not use rhetorical questions followed by obvious answers. State the assertion directly. - Prefer lists and tables over long paragraphs. +- Prefer descriptive names and links over invented identifiers. Follow the `documentation-style` skill for exceptions required by artifact-specific rules and for preserving existing references. - Mermaid: detect the platform via the remote (`git config --get remote.origin.url`). - Azure DevOps (`dev.azure.com` or `visualstudio.com`): use `:::mermaid` and `:::` - GitHub (`github.com`): use code block with ` ```mermaid ` and ` ``` ` diff --git a/.github/plugins/devsquad/skills/documentation-style/SKILL.md b/.github/plugins/devsquad/skills/documentation-style/SKILL.md index 16ca8b8..94c2825 100644 --- a/.github/plugins/devsquad/skills/documentation-style/SKILL.md +++ b/.github/plugins/devsquad/skills/documentation-style/SKILL.md @@ -32,6 +32,14 @@ This guide defines standards for all documentation generated in the project. - **Avoid**: rhetorical questions followed by an obvious answer ("The solution? Test everything that matters.") - **Prefer**: go straight to the statement with project-specific context. +## Names and References + +1. Use descriptive headings, scenario names, and plain statements instead of inventing codes for requirements, stories, tasks, assumptions, risks, or review findings. Do not replace numeric codes with another opaque naming scheme. +2. Add formal identifiers only when explicitly requested or required by an established project convention, compliance process, or artifact-specific template or instruction. Current spec templates and verification rules still require requirement and conformance IDs, so preserve those contracts until they are changed together. +3. Reference behavior by its descriptive name and document or section link when available. Use a precise link when names could be ambiguous. Preserve native board IDs, existing ADR numbers, and technical identifiers such as protocol fields and error codes. +4. Keep ordinary numbered procedures and meaningful numeric values. Avoid repeating the same requirement in multiple sections solely to assign it another identifier, while retaining distinct inputs, expected outcomes, and constraints. +5. Apply these defaults to newly written or rewritten text only. Preserve existing identifiers, anchors, and inbound references outside the requested scope. Convert an existing document only within an approved scope that includes its affected references. + ## Diagrams For diagram design, review, tool selection (Mermaid vs Draw.io), and platform rendering rules, use the `diagram-design` skill. diff --git a/.github/plugins/devsquad/skills/quality-gate/references/rubrica-tasks.md b/.github/plugins/devsquad/skills/quality-gate/references/rubrica-tasks.md index e133c67..1c8c9ef 100644 --- a/.github/plugins/devsquad/skills/quality-gate/references/rubrica-tasks.md +++ b/.github/plugins/devsquad/skills/quality-gate/references/rubrica-tasks.md @@ -17,6 +17,7 @@ | T6 | Incremental phases | Each phase is a complete and independently testable increment. | Analyze phases | | T7 | Complexity analyzed | Each user story had complexity analysis with known work, risks, and recommendation. | Check if complexity-analysis skill was applied | | T8 | Consistency with ADRs | Tasks reference correct technologies and versions per ADRs (ADR takes precedence over plan.md). | Cross-check tasks with ADRs | +| T9 | Readable board titles | Newly generated GitHub and Azure DevOps titles follow `work-item-creation` Title rules without invented sequential task or story identifiers. Required feature prefixes, meaningful domain numbers, native board IDs, and relationship links remain intact. | Check outgoing or newly created titles, without requiring a rename of existing work items | ## Cross-Verification (deep level) diff --git a/.github/plugins/devsquad/skills/work-item-creation/SKILL.md b/.github/plugins/devsquad/skills/work-item-creation/SKILL.md index 50cdc6d..59f0de7 100644 --- a/.github/plugins/devsquad/skills/work-item-creation/SKILL.md +++ b/.github/plugins/devsquad/skills/work-item-creation/SKILL.md @@ -10,7 +10,7 @@ Before creating ANY work item, verify: 1. **Platform**: Read `.memory/board-config.md` to identify GitHub or Azure DevOps 2. **Duplicates**: Check if a similar work item already exists on the board 3. **Required tags/labels**: all present (see section below) -4. **Title in correct format**: see Title section +4. **Title in correct format**: follow the Title section and check the outgoing title contains no invented sequential task or story identifier 5. **Body filled in**: per the platform format (see GitHub and Azure DevOps sections) 6. **Hierarchy**: parent linked correctly 7. **Durable descriptions**: body describes *behavior* using domain language, not implementation details (see Durability Rules below) @@ -26,6 +26,7 @@ Work items live on the board, get rendered in GitHub/ADO UIs, and are read by hu | No em-dash (—), en-dash (–), or hyphen as separator between concepts | Ambiguous in titles, breaks search, often AI-generated tell. Rewrite the sentence. | `Auth flow — refactor` → `Refactor auth flow` | | Never use `#` in free text | Azure DevOps auto-converts to a work item link, breaking references and creating wrong cross-links. Use "first", "third option", or rephrase. | `#1 priority` → `top priority` | | No contrastive constructions ("not just X, it's Y", "more than just", "goes beyond") | Generic AI framing that adds words without information | `This is not just a fix, it's a rethink` → `Replace the retry logic` | +| Descriptive names instead of invented identifiers | Keeps scenarios, assumptions, and risks readable without another numbering scheme. Preserve identifiers required by the source artifact or an established project convention, existing references, and native board IDs. | `RISK-001` added to a risk that can be described by name | | Direct active voice, no rhetorical questions | Work items are commands or descriptions, not essays | `What if we cached responses? We should cache them.` → `Cache responses for 60 seconds` | | No promotional or exaggerated language | Work items track work, not pitch it | `seamless`, `revolutionary`, `world-class` | | Keep titles short and concrete; bodies focused on observable behavior | Titles surface in lists; bodies are read once during planning and again during review | See Durability Rules for body content rules | @@ -157,6 +158,16 @@ Cache the list of existing labels to avoid repeated calls during the same creati - ADRs: `[ADR] ` or `[][ADR] ` - Tech Debt: `[Tech Debt] ` +For GitHub and Azure DevOps, do not add sequential task or story identifiers such as `T-1`, `T001`, or `US-01` to generated titles, including after the feature prefix. Do not copy local draft numbering into the title. The board supplies its own identity, and hierarchy and dependency links preserve relationships. + +| Avoid | Use | +|-------|-----| +| `T-1 [pix] Prevent duplicate payments` | `[pix] Prevent duplicate payments` | +| `[pix] T002 Validate payment limits` | `[pix] Validate payment limits` | +| `[pix] US-01 Send an immediate payment` | `[pix] Send an immediate payment` | + +Keep meaningful domain numbers and versions, such as `[pix] Support Pix API v2`. Apply the title rule to newly generated work items without renaming existing board items as a cleanup. + ## Hierarchy - Tasks are children of User Stories diff --git a/CHANGELOG.md b/CHANGELOG.md index c301570..0cc828c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,11 +18,14 @@ See `CONTRIBUTING.md` for full conventions. ### Template changes (consumer action required) +- Documentation style guidance now favors descriptive names and links over invented identifiers in newly written or rewritten text. Preserve existing references, native board IDs, ADR numbers, technical identifiers, and IDs still required by artifact-specific templates and verification rules. No automatic cleanup of existing documents is required. +- **Consumer action:** Update the DevSquad plugin and apply the naming guidance to existing `.github/copilot-instructions.md` and `.github/instructions/documentation-style.instructions.md`, or preview `sdd-init.sh update-all --dry-run` and review all planned overwrites before applying `sdd-init.sh update-all`. - Documentation style instructions and the `documentation-style` skill now explicitly forbid introducing the em-dash character (Unicode U+2014) in newly written or rewritten Markdown and discourage semicolons in prose. Recast sentences for natural flow while preserving their meaning, without mechanically replacing punctuation with abrupt sentence breaks. Semicolons required by code, technical syntax, or verbatim quotations remain allowed. Preserve existing text outside the requested scope. Existing documents do not require a cleanup. - **Consumer action:** Update the DevSquad plugin for the skill change. Apply the same scoped rules to existing `.github/copilot-instructions.md` and `.github/instructions/documentation-style.instructions.md` files, or preview `sdd-init.sh update-all --dry-run` and review all planned overwrites before applying `sdd-init.sh update-all` to refresh managed files. ### Changed +- Work item creation and decomposition now explicitly exclude invented sequential task and story identifiers from generated GitHub and Azure DevOps titles. The task quality rubric checks this convention while preserving feature prefixes, domain numbers, native board IDs, hierarchy, and dependency links. Existing work items are not renamed automatically. - The `test-discipline` skill now explicitly covers tautological assertions, independent behavioral oracles, and behavior-preserving refactoring. Implementation and review workers and the code quality rubric reinforce these checks. Reuse existing behavioral tests and add tests only for concrete coverage gaps, without requiring mutation-testing tooling or banning legitimate test helpers and computed expectations. ### Added (Agent Intent Governance — selective Architecture of Intent adoption) diff --git a/docs/src/content/docs/skills/quality.mdx b/docs/src/content/docs/skills/quality.mdx index 53e5e9d..122929c 100644 --- a/docs/src/content/docs/skills/quality.mdx +++ b/docs/src/content/docs/skills/quality.mdx @@ -139,12 +139,19 @@ Formatting and style rules for all markdown documentation generated in the proje | Separators | Rephrase sentences instead of separating concepts with hyphens | | Work item references | Never use `#` in free text (Azure DevOps auto-links) | | Structure | Lists and tables over long paragraphs | +| Names and references | Prefer descriptive names and links over invented codes for stories, requirements, scenarios, risks, and findings | | Length | Specs and ADRs should be 1-2 pages | Preserve meaning and natural flow rather than mechanically replacing semicolons with periods or splitting connected ideas into short, abrupt sentences. Keep semicolons required by code, technical syntax, or verbatim quotations. Preserve existing text outside the requested scope. Do not scan or rewrite documents solely to remove existing em dashes or semicolons. Ordinary hyphens in compound words, identifiers, Markdown lists, and tables remain allowed. +Use formal identifiers only when explicitly requested or required by an established project convention, compliance process, or artifact-specific rules. Keep ordinary numbered procedures, meaningful numeric values, native board IDs, existing ADR numbers, and technical identifiers. Avoid repeating the same requirement solely to assign another code. + +Apply the naming defaults only to newly written or rewritten text. Preserve existing identifiers and references outside the requested scope. Current spec templates and verification rules still require requirement and conformance IDs, which remain supported until those contracts are updated together. + +For generated work item titles, the `work-item-creation` skill explicitly excludes sequential task and story prefixes such as `T-1`, `T001`, and `US-01`. It retains feature prefixes and native board identity without renaming existing work items. + **Language rules:** | Avoid | Prefer | |-------|--------|