work

# Product specification workflow ## Usage ```text /work <area> <feature> /work ``` Use `workspace/<area>/projects/<feature>/` for active work. With no arguments, locate the most recently modified project under `workspace/`, infer its phase from current artifacts, and present the evidence before resuming. ## 1. Discovery Resolve the primary user, concrete problem, desired outcomes, constraints, dependencies, and non-goals. Save raw evidence, assumptions, and open questions to `notes.md`. ## 2. Draft Read `context/templates/spec_template.md` and create `spec-draft.md` with: - problem and why it matters now; - proposed user outcome and product behavior; - target users and key journeys; - measurable goals and explicit non-goals; - testable functionality and acceptance criteria; - success and guardrail metrics; - dependencies, risks, open decisions, and recovery behavior. Use placeholders for unknown author, initiative, issue, owner, and date fields. Do not convert a directional intent into an approved commitment. ## 3. Feasibility When source or architecture evidence is available, inspect it and create `feasibility-draft.md` with: - reusable infrastructure and current constraints; - technical gaps and credible options; - data, API, security, migration, observability, and rollout implications; - effort ranges with confidence and assumptions; - dependencies and owners when verified; - failure modes and test strategy. Label product intent separately from verified current-state engineering facts. ## 4. Resolve decisions Discuss one material gap at a time. Add each durable choice to `decisions.md`: ```markdown ## YYYY-MM-DD: [Decision] **Context:** [Question or constraint] **Decision:** [Chosen direction] **Rationale:** [Evidence and trade-off] **Alternatives considered:** - [Option] - [Why rejected or deferred] ``` Update the draft so it reflects the decision. Keep unresolved concerns in `notes.md` and in the spec's risks or open questions. ## 5. Promote Promote only after required decisions and acceptance criteria are resolved: 1. Read the draft, feasibility analysis, and decision log. 2. Reconcile contradictions and remove resolved TODOs. 3. Preserve remaining uncertainty explicitly. 4. Write the approved artifact to `workspace/<area>/specs/<feature>.md`. 5. Show the diff and validation evidence before any commit. Do not commit unless the user asked for a commit or the active workflow explicitly includes it. ## 6. Publish Offer publishing as a separate action. Use configured connectors when available, preview the target and transformed content, and require explicit confirmation before the external write. Otherwise leave a local publish-ready document.