ADR-393: Add template reference, revise mode, and concision pass to dev-spec pipeline

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`.

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_<FeatureName>.md` in PascalCase.
+Name: `_spec_<FeatureName>.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:
 

plugins/dev-team/skills/dev-spec-first-draft/assets/dev_spec_template.md

@@ -0,0 +1,106 @@
+# \<Feature Name\>
+
+> **Status:** Draft
+> **Design:** `_design_<FeatureName>.md` — the detailed design doc this spec implements, if one
+> exists; otherwise "— none"
+> **Architecture doc:** `_doc_<FeatureName>.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
+
+### \<Decision title\>
+
+_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 |
+|---|---|---|---|
+| `<Name>` | Wrapper \| Testable \| Orchestrator | One sentence | `<Component>`, `<Component>`, 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.

plugins/dev-team/skills/document-concision-pass/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: document-concision-pass
+user-invocable: false
+description: >
+  Use when a document needs a final tightening pass. Re-reads it section by section and cuts
+  restated context, redundant hedging, and multi-sentence explanations that could be one
+  sentence — without dropping any decision, requirement, or scenario.
+argument-hint: <path to document>
+---
+
+Use this skill when:
+- A document has just been drafted or extended and its prose has accumulated padding
+- You are running a final tightening pass before a document is considered done
+
+Takes one argument: the path to the document. Makes no assumption about which template (or
+whether any template) produced it — this skill works unchanged on a Proposal, a Detailed
+Design, a dev spec, a `SKILL.md` file, or any other markdown document.
+
+## Steps
+
+### 1 — Re-read the document
+
+Read the document in full using the Read tool.
+
+### 2 — Walk it section by section
+
+Split the document into its headings (each `##` block; use `#` blocks instead if the document
+has no `##` headings, or a nested `###` block where a `##` section is long enough that tightening
+it as a whole would be unwieldy). Working in document order, for each section:
+
+**a.** Re-read just that section's text.
+
+**Leave callout blocks untouched.** A `> [!NOTE]` / `> **Method:**` callout (defined by
+`playbook-contract`) records methodology rationale in flight for later harvesting, and a
+`> **Review:**` callout marks an open review comment — both are structurally distinct from
+ordinary prose and depend on their exact marker syntax for later grep-based/agent recognition.
+Skip both entirely in steps b–c: never reword, merge, or otherwise tighten a `> [!NOTE]` /
+`> **Method:**` or `> **Review:**` blockquote block.
+
+**b.** Look for concision opportunities within it:
+- Restated context the reader already has from an earlier section or from the section's own
+  heading
+- Redundant hedging ("it's worth noting that", "in general", a qualifier repeated more than
+  once) that doesn't change the meaning
+- A multi-sentence explanation that says no more than a single sentence would
+
+**c.** Tighten the section's wording with `Edit`. Cut only wording — never remove, merge away, or
+soften a decision, requirement, or scenario the section states. When in doubt whether a sentence
+is padding or load-bearing content, leave it as is.
+
+**d.** If the section needs no changes, move on without editing it.
+
+### 3 — Confirm nothing was lost
+
+Compare the tightened document against the full text read in step 1: every decision,
+requirement, and scenario present before must still be present — reworded is fine, dropped is
+not. If a cut in step 2 turns out to have removed something substantive, restore it (reworded, if
+that still reads more tightly than the original) before finishing.