sdd-2-specify

# SDD Phase 2: Specify Focus on user value. Do NOT include stack, framework, or technology choices in the specification. ## Inputs * **slug** (Optional): Slug from the Explore phase. Inferred from context if omitted. * **dossier** (Optional): Path to research dossier from SDD Phase 1. ## When to Read References Load only the reference the current problem needs: * Canonical spec section order and acceptance-criteria authoring rules: `.github/instructions/sdd-conventions.instructions.md` * Scoring CS-1 through CS-5: `docs/standards/harness-governance.md` * Evidence for goals, non-goals, and affected services: the Phase 1 `research-dossier.md` * Which services exist and what each owns: `AGENTS.md` ## Step 0: Doctrine Resolution Before starting, resolve project conventions: 1. Check for project doctrine files: * `docs/project-rules/` (constitution.md, rules.md, idioms.md, architecture.md) * `copilot-instructions.md`, `AGENTS.md`, `CONTRIBUTING.md`, `README.md` 2. If no doctrine found, scan the codebase: * Dependency manifests (package.json, *.csproj, Cargo.toml, pyproject.toml, go.mod) * Build system (Makefile, Justfile, Taskfile.yml, scripts/) * Test framework (test directories, test configuration files) * Directory patterns and naming conventions 3. Extract and document: * Build command, test command, coverage threshold (if any) * Naming conventions, module/service topology, CI platform 4. Unknown values become explicit `[TODO]` markers — never assume silently. ## Step 1: Load Research Context If a research dossier exists (at `{dossier}` or `.copilot-tracking/plans/{date}/{slug}/research-dossier.md`), read it and extract relevant findings. If no dossier is available, proceed with the information provided in the user's topic description. ## Step 2: Create Feature Specification Create `{slug}-spec.md` in `.copilot-tracking/plans/{date}/{slug}/` with the following canonical sections in strict order: ### Summary One-paragraph description of the feature in terms of user value and business outcome. ### Goals Bulleted list of what this feature achieves. Each goal is outcome-oriented and measurable. ### Non-Goals Explicitly scoped-out items. Prevents scope creep by naming what this feature does NOT do. ### Acceptance Criteria Numbered, testable scenarios that define "done." Each criterion follows the pattern: "Given [context], when [action], then [outcome]." Two criteria that cannot be satisfied before review, and must not gate it: * A criterion depending on the review's own output — verdict, fix cycles, finding density — belongs to a post-verdict step. Gating approval on it deadlocks the cycle: the value is unknown until review finishes, and review cannot approve without it. * A criterion using a vague quantifier ("recent", "reports it", "promptly") needs a testable bound at Specify time. Left open, it becomes a disagreement about wording during review rather than a finding about the implementation. ### Complexity Score Assign CS-1 through CS-5 using the project's complexity rubric from doctrine. Apply the 6-factor scoring model (Surface Area, Integration, Data/State, Novelty, NFR, Testing) if the rubric is documented. If no rubric is found in doctrine, use this default mapping: * CS-1: Single file, no integration, no new data. * CS-2: Few files in one module, minimal integration. * CS-3: Multiple modules, cross-service integration, or new data models. * CS-4: Architectural change, new external dependencies, or security implications. * CS-5: Platform-level change, new service, or fundamental pattern shift. ### Risks and Assumptions Known risks with likelihood and impact. Assumptions that underpin the specification. Mark uncertain items with `[NEEDS CLARIFICATION]`. ### Open Questions Unresolved decisions or information gaps. Each question identifies who can answer it and the impact of leaving it unresolved. ### Affected Modules/Services List of modules, services, or components that this feature touches or depends on, based on research findings or codebase analysis. ### Testing Strategy Placeholder for Phase 3 (Clarify) to populate. The testing approach (Standard, Lightweight, or None) is decided during clarification. `[NEEDS CLARIFICATION: Testing approach not yet decided — run SDD Phase 3 (Clarify)]` ### Workshop Opportunities Table of topics that would benefit from deeper design exploration before implementation: ```markdown | Topic | Type | Why It Matters | Priority | |-------|------|----------------|----------| ``` Types include: Data Model, API Contract, State Machine, Integration Pattern, Storage Design, or other design-specific categories. ## Step 3: Gate Check Scan the completed specification for `[NEEDS CLARIFICATION]` markers. If any exist, note them in the output summary. These do not block completion but signal that SDD Phase 3 (Clarify) should address them.