From e1c9b22564b0f2a34ab37fccff76fc770f9a0a8a Mon Sep 17 00:00:00 2001 From: Claude on behlaf of jodavis Date: Fri, 4 Sep 2026 00:16:30 +0000 Subject: [PATCH 1/4] ADR-393: Add re-entrancy check and final concision pass to write-dev-spec Inserts a new step 2 that checks documentation.dev-specs.search for an existing dev spec and, if found, has step 3 invoke dev-spec-first-draft in revise mode instead of first-draft mode. Adds a final step 9 that runs document-concision-pass over the finished spec, for symmetry with write-proposal/write-detailed-design. Also brings in document-concision-pass/SKILL.md (authored on ADR-390's still-open branch) so this reference resolves to a real skill, per ADR-393's stated dependency on ADR-390. --- plugins/dev-team/commands/write-dev-spec.md | 28 +++++++++++++++------ 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/plugins/dev-team/commands/write-dev-spec.md b/plugins/dev-team/commands/write-dev-spec.md index ca0cdca..6e0b39e 100644 --- a/plugins/dev-team/commands/write-dev-spec.md +++ b/plugins/dev-team/commands/write-dev-spec.md @@ -29,36 +29,50 @@ behavior questions. Record its path for `dev-spec-first-draft`'s `> **Design:**` If `gather-brief-sources` could not resolve any sources at all, tell the user and stop. -### 2 — Write the first draft +### 2 — Check for an existing dev spec + +Substitute the resolved `work-item-id` (if any) into `documentation.dev-specs.search` (from +`get-project-configuration`) and run the search. If a matching dev spec is found, read it in +full — the new brief is the reason for revision, not a from-scratch rewrite. Record its path; +step 3 invokes `dev-spec-first-draft` in revise mode instead of first-draft mode when this +happens. + +### 3 — Write the first draft Use the `dev-spec-first-draft` skill with the feature brief (and design doc, if found) to gather -context from docs, source code, and the user, and write the draft spec file. +context from docs, source code, and the user, and write the draft spec file. If step 2 found an +existing dev spec, invoke it in revise mode instead, passing the existing spec's path. **PAUSE — wait for the user to review the draft.** -### 3 — Refine the spec +### 4 — Refine the spec Use the `document-discussion` skill to resolve `> **Review:**` comments with the user. Repeat until the user says the document is ready. -### 4 — Task breakdown +### 5 — Task breakdown Use the `dev-spec-task-breakdown` skill to draft the spec's task breakdown and pause for user approval. -### 5 — Readiness review +### 6 — Readiness review Use the `document-readiness-review` skill on the spec file with `researcher-dev-spec-review` to verify the full spec — design content and task breakdown together — is implementation-ready and complete. -### 6 — Create tracked work items +### 7 — Create tracked work items Use the `dev-spec-create-work-items` skill to create tracked work items for the approved tasks (and any related features), link task dependencies in the tracker, and update the spec with the assigned keys. -### 7 — Update work items +### 8 — Update work items Use the `dev-spec-task-work-items` skill to update project work items with summaries of the finalized design decisions. + +### 9 — Final concision pass + +Use the `document-concision-pass` skill on the spec file to tighten it, for symmetry with +`write-proposal`/`write-detailed-design`. From d7edeb4c8977afbb393d35b46cf0fcc4017df96e Mon Sep 17 00:00:00 2001 From: Claude on behlaf of jodavis Date: Fri, 4 Sep 2026 00:17:09 +0000 Subject: [PATCH 2/4] ADR-393: Add revise mode, Contents-last note, tightened TBD language, and final concision pass to dev-spec-first-draft Inserts a new step 2 'Revising an existing document', mirroring proposal-first-draft/detailed-design-first-draft but adapted to this skill's existing batched-AskUserQuestion interaction style rather than a section-by-section interview rewrite. Step 3 (renumbered from step 2) now writes/regenerates the Contents section last, tightens the TBD/Open Questions language to require explicit user confirmation rather than a silent default, and ends with a document-concision-pass call. Also brings in the pre-authored assets/dev_spec_template.md (already linked by this file, but missing from this branch) from the still-open ADR-336 spec-authoring PR. --- .../skills/dev-spec-first-draft/SKILL.md | 25 ++++- .../assets/dev_spec_template.md | 106 ++++++++++++++++++ 2 files changed, 125 insertions(+), 6 deletions(-) create mode 100644 plugins/dev-team/skills/dev-spec-first-draft/assets/dev_spec_template.md diff --git a/plugins/dev-team/skills/dev-spec-first-draft/SKILL.md b/plugins/dev-team/skills/dev-spec-first-draft/SKILL.md index 40df951..18bb57a 100644 --- a/plugins/dev-team/skills/dev-spec-first-draft/SKILL.md +++ b/plugins/dev-team/skills/dev-spec-first-draft/SKILL.md @@ -36,20 +36,33 @@ Skip questions you can already answer from docs, the design doc, or source. Prov If answers raise new ambiguities that would materially affect the spec, ask one more targeted follow-up round. Otherwise proceed. -Treat this step as the place unresolved questions get eliminated, not deferred. If you notice a gap while writing the draft in step 2, stop and go back through this same research/`AskUserQuestion` process before continuing — do not carry it forward into the draft's Open Questions section instead. An item belongs in Open Questions only if the user was asked and explicitly said something like "I don't know, we'll have to figure that out as we go" — a genuinely open question that can't be resolved by research or a decision right now. It is not for questions you simply haven't asked yet, or that research could answer. +Treat this step as the place unresolved questions get eliminated, not deferred. If you notice a gap while writing the draft in step 3, stop and go back through this same research/`AskUserQuestion` process before continuing — do not carry it forward into the draft's Open Questions section instead. An item belongs in Open Questions only if the user was asked and explicitly said something like "I don't know, we'll have to figure that out as we go" — a genuinely open question that can't be resolved by research or a decision right now. It is not for questions you simply haven't asked yet, or that research could answer. -### 2 — Write the first draft +### 2 — Revising an existing document + +If a dev spec for this feature/task already exists, the calling command will have already found +it and will be invoking this skill in revise mode, passing its path. Read the existing document +in full. Treat the new brief as the reason for revision, not as a from-scratch rewrite: use step +1's research/`AskUserQuestion` process to ask what actually changes — a revision may touch +several existing sections, not just append one bounded new part. Continue to step 3 once every +changed section is resolved. + +### 3 — Write the first draft Determine the spec file location: the `_spec_*.md` lives next to the code it describes — in the directory where the new feature's code will live. -Name: `_spec_.md` in PascalCase. +Name: `_spec_.md` in PascalCase. Skip this location step if revising an existing document — use its current location instead. -Write the file following the template at +Write (or update) the file following the template at [`assets/dev_spec_template.md`](assets/dev_spec_template.md). -Fill every section with resolved content — research or ask about anything you don't yet know before writing it in, using step 1's process. Reserve `> TBD: reason` and the Open Questions section only for items the user explicitly deferred (e.g. "we'll figure it out as we go"), not for questions you simply haven't asked yet. +Fill every section with resolved content — research or ask about anything you don't yet know before writing it in, using step 1's process. A `> TBD: reason` or an Open Questions entry may only remain when the user has explicitly confirmed it should stay open (e.g. "we'll figure it out as we go") — never a silent default when drafting wraps up, and never for a question you simply haven't asked yet. Confirm with the user before leaving anything open. + +Write or regenerate the `## Contents` section last, once every other section is in its final form, per the template's own note. + +Once the draft is complete, invoke the `document-concision-pass` skill on the file to tighten it. -### 3 — Pause for review +### 4 — Pause for review After writing, tell the user: diff --git a/plugins/dev-team/skills/dev-spec-first-draft/assets/dev_spec_template.md b/plugins/dev-team/skills/dev-spec-first-draft/assets/dev_spec_template.md new file mode 100644 index 0000000..0bb5b2e --- /dev/null +++ b/plugins/dev-team/skills/dev-spec-first-draft/assets/dev_spec_template.md @@ -0,0 +1,106 @@ +# \ + +> **Status:** Draft +> **Design:** `_design_.md` — the detailed design doc this spec implements, if one +> exists; otherwise "— none" +> **Architecture doc:** `_doc_.md` — authored by `dev-spec-task-breakdown`'s +> unconditional final "Author design documentation" task once implementation completes; this +> spec persists afterward for harvesting + +This line names an obligation owned by `dev-spec-task-breakdown`, not by this skill: every task +breakdown must append that unconditional final documentation task, so the reference above is +always honored. If `dev-spec-task-breakdown` does not yet append it, treat that as a gap in +`dev-spec-task-breakdown`, not a reason to omit the header line here. + +## Contents + +_(Write or regenerate this section last, after every other section is in place, so it reflects +the final heading set rather than a stale mid-draft one.)_ + +- [Overview](#overview) +- [Responsibilities & Boundaries](#responsibilities--boundaries) +- [Key Design Decisions](#key-design-decisions) +- [Component Breakdown](#component-breakdown) +- [Planned Implementation](#planned-implementation) +- [Related Features](#related-features) +- [Open Questions](#open-questions) +- [Related Docs](#related-docs) + +## Overview + +One paragraph: what this feature does and why it exists. + +## Responsibilities & Boundaries + +- **Owns:** ... +- **Does not own:** ... +- **Integrates with:** ... + +## Key Design Decisions + +### \ + +_Context:_ Why this choice was needed. +_Decision:_ What was decided. +_Consequences:_ Trade-offs accepted. + +_(Repeat for each significant decision.)_ + +## Component Breakdown + +| Component | Type | Responsibility | Depends on | +|---|---|---|---| +| `` | Wrapper \| Testable \| Orchestrator | One sentence | ``, ``, or — | + +Use the `component-taxonomy` skill for the Wrapper/Testable/Orchestrator definitions and the +property-level Wrapper carve-out to classify every planned component. + +When identifying Testable components, apply these isolation patterns as authoring guidance: + +- Prefer dependency injection to isolate a component from its collaborators. +- Consider the **State Object** pattern for stateful components: state lives as plain, + directly-observable fields on a data object. By default, only the owning/controller + service mutates it; other services may read it. Some components legitimately invert + this — a ViewModel-style State Object is written directly by its consumer (e.g. the UI), + and the owning controller subscribes to change notifications on it to react. In this + inverted case, both sides may read and write the object; design each field's ownership + deliberately rather than assuming a single default direction. +- Prefer synchronous logic for anything complex; gather async data up front and pass the + results in, rather than doing async work on demand inside complex logic. +- Where practical, build each component before its dependencies exist, using mocks of the + interfaces, so the dependency interfaces reflect real usage rather than speculative design. + +## Planned Implementation + +### Interfaces + +Public interfaces — method signatures, types, and responsibilities. + +### Key Classes + +Planned classes, their roles, and important relationships. + +### Data Flow + +How data moves through the feature from trigger to output. + +## Related Features + +Features identified during drafting that are out of scope here and will be spec'd separately. + +| Feature | Scope | +|------|-------| +| (this feature) | ... | + +_(Omit if there are no related features.)_ + +## Open Questions + +_(Reserved for items the user explicitly deferred — see step 1. An empty section is the normal, +expected outcome.)_ + +- [ ] Unresolved question + +## Related Docs + +Links to the documentation files consulted during drafting. From d467260844d8be459918bb735f704482ccd42195 Mon Sep 17 00:00:00 2001 From: Claude on behlaf of jodavis Date: Tue, 15 Sep 2026 12:17:44 +0000 Subject: [PATCH 3/4] ADR-393: Address review comments on dev_spec_template.md and dev-spec-first-draft MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - dev_spec_template.md: stop hard-coding the _design_.md / _doc_.md naming patterns in the Design/Architecture doc header lines; describe them as resolved via documentation.specs / documentation.architecture instead, matching the ADR-387 precedent. - dev_spec_template.md: encourage Mermaid diagrams in Key Classes and Data Flow where they'd be clearer than prose. - dev-spec-first-draft/SKILL.md: rewrite from a "new or revising" perspective throughout instead of a separate bolted-on revising step, matching PR #171's structural pattern. Keeps the existing batched AskUserQuestion gathering style unchanged — adopting the section-by- section conversational interview is a separate, larger change the spec author is deferring. --- .../skills/dev-spec-first-draft/SKILL.md | 35 +++++++++---------- .../assets/dev_spec_template.md | 16 +++++---- 2 files changed, 25 insertions(+), 26 deletions(-) diff --git a/plugins/dev-team/skills/dev-spec-first-draft/SKILL.md b/plugins/dev-team/skills/dev-spec-first-draft/SKILL.md index 18bb57a..0865443 100644 --- a/plugins/dev-team/skills/dev-spec-first-draft/SKILL.md +++ b/plugins/dev-team/skills/dev-spec-first-draft/SKILL.md @@ -2,18 +2,26 @@ name: dev-spec-first-draft user-invocable: false description: > - Use when writing a first draft of a complete new dev spec or a new part of an existing dev spec. - Gathers context from docs, source code, and the user, then writes the draft to a _spec_*.md file. + Use when writing a dev spec — a new one, or revising an existing one with new information. + Gathers context from docs, source code, and the user, then writes the draft to a location + next to the feature's code. argument-hint: --- Use this skill when: -- You are writing a first draft of a complete new dev spec or a new part of an existing dev spec +- You are writing a dev spec, whether drafting a new one or revising an existing one with new information + +You are writing a dev spec — a new one, or revising an existing one whose path the caller passed +in. ## Steps ### 1 — Gather context +If revising, the calling command has already found the existing dev spec and passed its path — +read it in full now, and treat the new brief as the reason for revision rather than a +from-scratch rewrite. + Use the `find-repo-documentation` skill to read the architecture docs relevant to the feature area. If a design doc is already known (passed in, or found via `documentation.specs.search` for the @@ -22,7 +30,7 @@ questions — do not re-ask those; only ask what the design doc leaves open for Spawn one or more `dev-team:researcher` agents to research any frameworks, libraries, or patterns the feature will use. Each agent uses the `research-learn` skill and returns findings with source links. -Use `AskUserQuestion` to ask the user focused questions that fill gaps the docs, design doc, and feature description don't answer. Good questions cover: +Use `AskUserQuestion` to ask the user focused questions that fill gaps the docs, design doc, and feature description don't answer — if revising, focus on what actually changes rather than re-asking settled ground. Good questions cover: - Ownership and boundaries (what this feature owns vs. delegates) - Integration points with existing subsystems @@ -36,22 +44,11 @@ Skip questions you can already answer from docs, the design doc, or source. Prov If answers raise new ambiguities that would materially affect the spec, ask one more targeted follow-up round. Otherwise proceed. -Treat this step as the place unresolved questions get eliminated, not deferred. If you notice a gap while writing the draft in step 3, stop and go back through this same research/`AskUserQuestion` process before continuing — do not carry it forward into the draft's Open Questions section instead. An item belongs in Open Questions only if the user was asked and explicitly said something like "I don't know, we'll have to figure that out as we go" — a genuinely open question that can't be resolved by research or a decision right now. It is not for questions you simply haven't asked yet, or that research could answer. - -### 2 — Revising an existing document - -If a dev spec for this feature/task already exists, the calling command will have already found -it and will be invoking this skill in revise mode, passing its path. Read the existing document -in full. Treat the new brief as the reason for revision, not as a from-scratch rewrite: use step -1's research/`AskUserQuestion` process to ask what actually changes — a revision may touch -several existing sections, not just append one bounded new part. Continue to step 3 once every -changed section is resolved. - -### 3 — Write the first draft +Treat this step as the place unresolved questions get eliminated, not deferred. If you notice a gap while writing the draft in step 2, stop and go back through this same research/`AskUserQuestion` process before continuing — do not carry it forward into the draft's Open Questions section instead. An item belongs in Open Questions only if the user was asked and explicitly said something like "I don't know, we'll have to figure that out as we go" — a genuinely open question that can't be resolved by research or a decision right now. It is not for questions you simply haven't asked yet, or that research could answer. -Determine the spec file location: the `_spec_*.md` lives next to the code it describes — in the directory where the new feature's code will live. +### 2 — Write the draft -Name: `_spec_.md` in PascalCase. Skip this location step if revising an existing document — use its current location instead. +If drafting new, determine the spec file location: the `_spec_*.md` lives next to the code it describes — in the directory where the new feature's code will live. Name it `_spec_.md` in PascalCase. If revising, use the existing document's location instead. Write (or update) the file following the template at [`assets/dev_spec_template.md`](assets/dev_spec_template.md). @@ -62,7 +59,7 @@ Write or regenerate the `## Contents` section last, once every other section is Once the draft is complete, invoke the `document-concision-pass` skill on the file to tighten it. -### 4 — Pause for review +### 3 — Pause for review After writing, tell the user: diff --git a/plugins/dev-team/skills/dev-spec-first-draft/assets/dev_spec_template.md b/plugins/dev-team/skills/dev-spec-first-draft/assets/dev_spec_template.md index 0bb5b2e..039e7d2 100644 --- a/plugins/dev-team/skills/dev-spec-first-draft/assets/dev_spec_template.md +++ b/plugins/dev-team/skills/dev-spec-first-draft/assets/dev_spec_template.md @@ -1,11 +1,11 @@ # \ > **Status:** Draft -> **Design:** `_design_.md` — the detailed design doc this spec implements, if one -> exists; otherwise "— none" -> **Architecture doc:** `_doc_.md` — authored by `dev-spec-task-breakdown`'s -> unconditional final "Author design documentation" task once implementation completes; this -> spec persists afterward for harvesting +> **Design:** \ `documentation.specs`\>, if one exists; otherwise "— none" +> **Architecture doc:** \ +> — authored by `dev-spec-task-breakdown`'s unconditional final "Author design documentation" task +> once implementation completes; this spec persists afterward for harvesting This line names an obligation owned by `dev-spec-task-breakdown`, not by this skill: every task breakdown must append that unconditional final documentation task, so the reference above is @@ -78,11 +78,13 @@ Public interfaces — method signatures, types, and responsibilities. ### Key Classes -Planned classes, their roles, and important relationships. +Planned classes, their roles, and important relationships. Use a Mermaid class or flowchart +diagram to illustrate the relationships where that's clearer than prose. ### Data Flow -How data moves through the feature from trigger to output. +How data moves through the feature from trigger to output. Use a Mermaid sequence or flowchart +diagram to illustrate the flow where that's clearer than prose. ## Related Features From ecc12a69b6a7f5d259688a28b85e25c26003d8af Mon Sep 17 00:00:00 2001 From: Claude on behlaf of jodavis Date: Tue, 15 Sep 2026 12:52:43 +0000 Subject: [PATCH 4/4] ADR-393: Address follow-up review comments on dev-spec-first-draft - When revising, reuse the existing spec's ## Related Docs section instead of re-discovering architecture docs and spawning fresh research from scratch; only look further for gaps the new brief raises. Matches the same fix already applied to proposal-first-draft in PR #171. - Stop naming the _spec_.md pattern explicitly in step 2; resolve the file's location and naming via write-repo-documentation's documentation.dev-specs placement instead, matching the pattern already applied to the template's own header lines and to detailed-design-first-draft in PR #171. --- .../skills/dev-spec-first-draft/SKILL.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/plugins/dev-team/skills/dev-spec-first-draft/SKILL.md b/plugins/dev-team/skills/dev-spec-first-draft/SKILL.md index 0865443..920b189 100644 --- a/plugins/dev-team/skills/dev-spec-first-draft/SKILL.md +++ b/plugins/dev-team/skills/dev-spec-first-draft/SKILL.md @@ -3,8 +3,8 @@ name: dev-spec-first-draft user-invocable: false description: > Use when writing a dev spec — a new one, or revising an existing one with new information. - Gathers context from docs, source code, and the user, then writes the draft to a location - next to the feature's code. + Gathers context from docs, source code, and the user, then writes the draft to the location + resolved via `documentation.dev-specs`. argument-hint: --- @@ -20,7 +20,9 @@ in. If revising, the calling command has already found the existing dev spec and passed its path — read it in full now, and treat the new brief as the reason for revision rather than a -from-scratch rewrite. +from-scratch rewrite. Its `## Related Docs` section already records the architecture docs and +design doc consulted during the prior pass — reuse that instead of re-discovering them from +scratch, and only look further for gaps the new brief actually raises. Use the `find-repo-documentation` skill to read the architecture docs relevant to the feature area. @@ -28,7 +30,10 @@ If a design doc is already known (passed in, or found via `documentation.specs.s resolved work item), read it in full first. It already answers the problem/goals/behavior questions — do not re-ask those; only ask what the design doc leaves open for the implementation. -Spawn one or more `dev-team:researcher` agents to research any frameworks, libraries, or patterns the feature will use. Each agent uses the `research-learn` skill and returns findings with source links. +Spawn one or more `dev-team:researcher` agents to research any frameworks, libraries, or patterns +the feature will use — skip this if revising and the existing spec's research already covers the +new brief's scope. Each agent uses the `research-learn` skill and returns findings with source +links. Use `AskUserQuestion` to ask the user focused questions that fill gaps the docs, design doc, and feature description don't answer — if revising, focus on what actually changes rather than re-asking settled ground. Good questions cover: @@ -48,7 +53,8 @@ Treat this step as the place unresolved questions get eliminated, not deferred. ### 2 — Write the draft -If drafting new, determine the spec file location: the `_spec_*.md` lives next to the code it describes — in the directory where the new feature's code will live. Name it `_spec_.md` in PascalCase. If revising, use the existing document's location instead. +If drafting new, resolve the file's location and naming via the `write-repo-documentation` skill's +`documentation.dev-specs` placement. If revising, use the existing document's location instead. Write (or update) the file following the template at [`assets/dev_spec_template.md`](assets/dev_spec_template.md).