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`. 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..920b189 100644 --- a/plugins/dev-team/skills/dev-spec-first-draft/SKILL.md +++ b/plugins/dev-team/skills/dev-spec-first-draft/SKILL.md @@ -2,27 +2,40 @@ 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 the location + resolved via `documentation.dev-specs`. 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. 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. If a design doc is already known (passed in, or found via `documentation.specs.search` for the 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. 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 @@ -38,16 +51,19 @@ If answers raise new ambiguities that would materially affect the spec, ask one 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. -### 2 — 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. +### 2 — Write the draft -Name: `_spec_.md` in PascalCase. +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 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 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..039e7d2 --- /dev/null +++ b/plugins/dev-team/skills/dev-spec-first-draft/assets/dev_spec_template.md @@ -0,0 +1,108 @@ +# \ + +> **Status:** Draft +> **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 +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. 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. Use a Mermaid sequence or flowchart +diagram to illustrate the flow where that's clearer than prose. + +## 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.