[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7ARFR21S9DTR2PVCTGVXTQN":3,"skill-same:01M7ARFR21S9DTR2PVCTGVXTQN":73},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":29,"updatedAt":30,"install":31,"resources":44},"01M7ARFR21S9DTR2PVCTGVXTQN","spec-driven-workflow",null,"Use when the user asks to write specs before code, define acceptance criteria, plan features before implementation, generate tests from specifications, or follow spec-first development practices.","GongYuanCaiJi\u002Fdsh-claude-skills","GongYuanCaiJi","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F129952120?v=4","01M7AK39Q4W3VPF7C1K8M58BFX","劉昱廷 Yu-Ting Liu","01M7APPQ7AEZTDQB0N6HCPTR2X",0,"MIT","https:\u002F\u002Fgithub.com\u002FGongYuanCaiJi\u002Fdsh-claude-skills\u002Fblob\u002Fmain\u002Fengineering\u002Fskills\u002Fspec-driven-workflow\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: \"spec-driven-workflow\"\ndescription: \"Use when the user asks to write specs before code, define acceptance criteria, plan features before implementation, generate tests from specifications, or follow spec-first development practices.\"\n---\n\n# Spec-Driven Workflow — POWERFUL\n\n## Overview\n\nSpec-driven workflow enforces a single, non-negotiable rule: **write the specification BEFORE you write any code.** Not alongside. Not after. Before.\n\nThis is not documentation. This is a contract. A spec defines what the system MUST do, what it SHOULD do, and what it explicitly WILL NOT do. Every line of code you write traces back to a requirement in the spec. Every test traces back to an acceptance criterion. If it is not in the spec, it does not get built.\n\n### Why Spec-First Matters\n\n1. **Eliminates rework.** 60-80% of defects originate from requirements, not implementation. Catching ambiguity in a spec costs minutes; catching it in production costs days.\n2. **Forces clarity.** If you cannot write what the system should do in plain language, you do not understand the problem well enough to write code.\n3. **Enables parallelism.** Once a spec is approved, frontend, backend, QA, and documentation can all start simultaneously.\n4. **Creates accountability.** The spec is the definition of done. No arguments about whether a feature is \"complete\" — either it satisfies the acceptance criteria or it does not.\n5. **Feeds TDD directly.** Acceptance criteria in Given\u002FWhen\u002FThen format translate 1:1 into test cases. The spec IS the test plan.\n\n### The Iron Law\n\n```\nNO CODE WITHOUT AN APPROVED SPEC.\nNO EXCEPTIONS. NO \"QUICK PROTOTYPES.\" NO \"I'LL DOCUMENT IT LATER.\"\n```\n\nIf the spec is not written, reviewed, and approved, implementation does not begin. Period.\n\n---\n\n## The Spec Format\n\nEvery spec follows this structure. No sections are optional — if a section does not apply, write \"N\u002FA — [reason]\" so reviewers know it was considered, not forgotten.\n\n### Mandatory Sections\n\n| # | Section | Key Rules |\n|---|---------|-----------|\n| 1 | **Title and Metadata** | Author, date, status (Draft\u002FIn Review\u002FApproved\u002FSuperseded), reviewers |\n| 2 | **Context** | Why this feature exists. 2-4 paragraphs with evidence (metrics, tickets). |\n| 3 | **Functional Requirements** | RFC 2119 keywords (MUST\u002FSHOULD\u002FMAY). Numbered FR-N. Each is atomic and testable. |\n| 4 | **Non-Functional Requirements** | Performance, security, accessibility, scalability, reliability — all with measurable thresholds. |\n| 5 | **Acceptance Criteria** | Given\u002FWhen\u002FThen format. Every AC references at least one FR-* or NFR-*. |\n| 6 | **Edge Cases** | Numbered EC-N. Cover failure modes for every external dependency. |\n| 7 | **API Contracts** | TypeScript-style interfaces. Cover success and error responses. |\n| 8 | **Data Models** | Table format with field, type, constraints. Every entity from requirements must have a model. |\n| 9 | **Out of Scope** | Explicit exclusions with reasons. Prevents scope creep during implementation. |\n\n### RFC 2119 Keywords\n\n| Keyword | Meaning |\n|---------|---------|\n| **MUST** | Absolute requirement. Non-conformant without it. |\n| **MUST NOT** | Absolute prohibition. |\n| **SHOULD** | Recommended. Omit only with documented justification. |\n| **MAY** | Optional. Implementer's discretion. |\n\nSee [spec_format_guide.md](references\u002Fspec_format_guide.md) for the complete template with section-by-section examples, good\u002Fbad requirement patterns, and feature-type templates (CRUD, Integration, Migration).\n\nSee [acceptance_criteria_patterns.md](references\u002Facceptance_criteria_patterns.md) for a full pattern library of Given\u002FWhen\u002FThen criteria across authentication, CRUD, search, file upload, payment, notification, and accessibility scenarios.\n\n---\n\n## Bounded Autonomy Rules\n\nThese rules define when an agent (human or AI) MUST stop and ask for guidance vs. when they can proceed independently.\n\n### STOP and Ask When:\n\n1. **Scope creep detected.** The implementation requires something not in the spec. Even if it seems obviously needed, STOP. The spec might have excluded it deliberately.\n\n2. **Ambiguity exceeds 30%.** If you cannot determine the correct behavior from the spec for more than 30% of a given requirement, the spec is incomplete. Do not guess.\n\n3. **Breaking changes required.** The implementation would change an existing API contract, database schema, or public interface. Always escalate.\n\n4. **Security implications.** Any change that touches authentication, authorization, encryption, or PII handling requires explicit approval.\n\n5. **Performance characteristics unknown.** If a requirement says \"MUST complete in \u003C 500ms\" but you have no way to measure or guarantee that, escalate before implementing a guess.\n\n6. **Cross-team dependencies.** If the spec requires coordination with another team or service, confirm the dependency before building against it.\n\n### Continue Autonomously When:\n\n1. **Spec is clear and unambiguous** for the current task.\n2. **All acceptance criteria have passing tests** and you are refactoring internals.\n3. **Changes are non-breaking** — no public API, schema, or behavior changes.\n4. **Implementation is a direct translation** of a well-defined acceptance criterion.\n5. **Error handling follows established patterns** already documented in the codebase.\n\n### Escalation Protocol\n\nWhen you must stop, provide:\n\n```markdown\n## Escalation: [Brief Title]\n\n**Blocked on:** [requirement ID, e.g., FR-3]\n**Question:** [Specific, answerable question — not \"what should I do?\"]\n**Options considered:**\n  A. [Option] — Pros: [...] Cons: [...]\n  B. [Option] — Pros: [...] Cons: [...]\n**My recommendation:** [A or B, with reasoning]\n**Impact of waiting:** [What is blocked until this is resolved?]\n```\n\nNever escalate without a recommendation. Never present an open-ended question. Always give options.\n\nSee `references\u002Fbounded_autonomy_rules.md` for the complete decision matrix.\n\n---\n\n## Workflow — 6 Phases\n\n### Phase 1: Gather Requirements\n\n**Goal:** Understand what needs to be built and why.\n\n1. **Interview the user.** Ask:\n   - What problem does this solve?\n   - Who are the users?\n   - What does success look like?\n   - What explicitly should NOT be built?\n2. **Read existing code.** Understand the current system before proposing changes.\n3. **Identify constraints.** Performance budgets, security requirements, backward compatibility.\n4. **List unknowns.** Every unknown is a risk. Surface them now, not during implementation.\n\n**Exit criteria:** You can explain the feature to someone unfamiliar with the project in 2 minutes.\n\n### Phase 2: Write Spec\n\n**Goal:** Produce a complete spec document following The Spec Format above.\n\n1. Fill every section of the template. No section left blank.\n2. Number all requirements (FR-*, NFR-*, AC-*, EC-*, OS-*).\n3. Use RFC 2119 keywords precisely.\n4. Write acceptance criteria in Given\u002FWhen\u002FThen format.\n5. Define API contracts with TypeScript-style types.\n6. List explicit exclusions in Out of Scope.\n\n**Exit criteria:** The spec can be handed to a developer who was not in the requirements meeting, and they can implement the feature without asking clarifying questions.\n\n### Phase 3: Validate Spec\n\n**Goal:** Verify the spec is complete, consistent, and implementable.\n\nRun `spec_validator.py` against the spec file:\n\n```bash\npython spec_validator.py --file spec.md --strict\n```\n\nManual validation checklist:\n- [ ] Every functional requirement has at least one acceptance criterion\n- [ ] Every acceptance criterion is testable (no subjective language)\n- [ ] API contracts cover all endpoints mentioned in requirements\n- [ ] Data models cover all entities mentioned in requirements\n- [ ] Edge cases cover failure modes for every external dependency\n- [ ] Out of scope is explicit about what was considered and rejected\n- [ ] Non-functional requirements have measurable thresholds\n\n**Exit criteria:** Spec scores 80+ on validator, and all manual checklist items pass.\n\n### Phase 4: Generate Tests\n\n**Goal:** Extract test cases from acceptance criteria before writing implementation code.\n\nRun `test_extractor.py` against the approved spec:\n\n```bash\npython test_extractor.py --file spec.md --framework pytest --output tests\u002F\n```\n\n1. Each acceptance criterion becomes one or more test cases.\n2. Each edge case becomes a test case.\n3. Tests are stubs — they define the assertion but not the implementation.\n4. All tests MUST fail initially (red phase of TDD).\n\n**Exit criteria:** You have a test file where every test fails with \"not implemented\" or equivalent.\n\n### Phase 5: Implement\n\n**Goal:** Write code that makes failing tests pass, one acceptance criterion at a time.\n\n1. Pick one acceptance criterion (start with the simplest).\n2. Make its test(s) pass with minimal code.\n3. Run the full test suite — no regressions.\n4. Commit.\n5. Pick the next acceptance criterion. Repeat.\n\n**Rules:**\n- Do NOT implement anything not in the spec.\n- Do NOT optimize before all acceptance criteria pass.\n- Do NOT refactor before all acceptance criteria pass.\n- If you discover a missing requirement, STOP and update the spec first.\n\n**Exit criteria:** All tests pass. All acceptance criteria satisfied.\n\n### Phase 6: Self-Review\n\n**Goal:** Verify implementation matches spec before marking done.\n\nRun through the Self-Review Checklist below. If any item fails, fix it before declaring the task complete.\n\n---\n\n## Self-Review Checklist\n\nBefore marking any implementation as done, verify ALL of the following:\n\n- [ ] **Every acceptance criterion has a passing test.** No exceptions. If AC-3 exists, a test for AC-3 exists and passes.\n- [ ] **Every edge case has a test.** EC-1 through EC-N all have corresponding test cases.\n- [ ] **No scope creep.** The implementation does not include features not in the spec. If you added something, either update the spec or remove it.\n- [ ] **API contracts match implementation.** Request\u002Fresponse shapes in code match the spec exactly. Field names, types, status codes — all of it.\n- [ ] **Error scenarios tested.** Every error response defined in the spec has a test that triggers it.\n- [ ] **Non-functional requirements verified.** If the spec says \u003C 500ms, you have evidence (benchmark, load test, profiling) that it meets the threshold.\n- [ ] **Data model matches.** Database schema matches the spec. No extra columns, no missing constraints.\n- [ ] **Out-of-scope items not built.** Double-check that nothing from the Out of Scope section leaked into the implementation.\n\n---\n\n## Integration with TDD Guide\n\nSpec-driven workflow and TDD are complementary, not competing:\n\n```\nSpec-Driven Workflow          TDD (Red-Green-Refactor)\n─────────────────────         ──────────────────────────\nPhase 1: Gather Requirements\nPhase 2: Write Spec\nPhase 3: Validate Spec\nPhase 4: Generate Tests  ──→  RED: Tests exist and fail\nPhase 5: Implement       ──→  GREEN: Minimal code to pass\nPhase 6: Self-Review     ──→  REFACTOR: Clean up internals\n```\n\n**The handoff:** Spec-driven workflow produces the test stubs (Phase 4). TDD takes over from there. The spec tells you WHAT to test. TDD tells you HOW to implement.\n\nUse `engineering-team\u002Ftdd-guide` for:\n- Red-green-refactor cycle discipline\n- Coverage analysis and gap detection\n- Framework-specific test patterns (Jest, Pytest, JUnit)\n\nUse `engineering\u002Fspec-driven-workflow` for:\n- Defining what to build before building it\n- Acceptance criteria authoring\n- Completeness validation\n- Scope control\n\n---\n\n## Examples\n\nA complete worked example (Password Reset spec with extracted test cases) is available in [spec_format_guide.md](references\u002Fspec_format_guide.md#full-example-password-reset). It demonstrates all 9 sections, requirement numbering, acceptance criteria, edge cases, and the corresponding pytest stubs generated by `test_extractor.py`.\n\n---\n\n## Anti-Patterns\n\n### 1. Coding Before Spec Approval\n\n**Symptom:** \"I'll start coding while the spec is being reviewed.\"\n**Problem:** The review will surface changes. Now you have code that implements a rejected design.\n**Rule:** Implementation does not begin until spec status is \"Approved.\"\n\n### 2. Vague Acceptance Criteria\n\n**Symptom:** \"The system should work well\" or \"The UI should be responsive.\"\n**Problem:** Untestable. What does \"well\" mean? What does \"responsive\" mean?\n**Rule:** Every acceptance criterion must be verifiable by a machine. If you cannot write a test for it, rewrite the criterion.\n\n### 3. Missing Edge Cases\n\n**Symptom:** Happy path is specified, error paths are not.\n**Problem:** Developers invent error handling on the fly, leading to inconsistent behavior.\n**Rule:** For every external dependency (API, database, file system, user input), specify at least one failure scenario.\n\n### 4. Spec as Post-Hoc Documentation\n\n**Symptom:** \"Let me write the spec now that the feature is done.\"\n**Problem:** This is documentation, not specification. It describes what was built, not what should have been built. It cannot catch design errors because the design is already frozen.\n**Rule:** If the spec was written after the code, it is not a spec. Relabel it as documentation.\n\n### 5. Gold-Plating Beyond Spec\n\n**Symptom:** \"While I was in there, I also added...\"\n**Problem:** Untested code. Unreviewed design. Potential for subtle bugs in the \"bonus\" feature.\n**Rule:** If it is not in the spec, it does not get built. File a new spec for additional features.\n\n### 6. Acceptance Criteria Without Requirement Traceability\n\n**Symptom:** AC-7 exists but does not reference any FR-* or NFR-*.\n**Problem:** Orphaned criteria mean either a requirement is missing or the criterion is unnecessary.\n**Rule:** Every AC-* MUST reference at least one FR-* or NFR-*.\n\n### 7. Skipping Validation\n\n**Symptom:** \"The spec looks fine, let's just start.\"\n**Problem:** Missing sections discovered during implementation cause blocking delays.\n**Rule:** Always run `spec_validator.py --strict` before starting implementation. Fix all warnings.\n\n---\n\n## Cross-References\n\n- **`engineering-team\u002Ftdd-guide`** — Red-green-refactor cycle, test generation, coverage analysis. Use after Phase 4 of this workflow.\n- **`engineering\u002Ffocused-fix`** — Deep-dive feature repair. When a spec-driven implementation has systemic issues, use focused-fix for diagnosis.\n- **`engineering\u002Frag-architect`** — If the feature involves retrieval or knowledge systems, use rag-architect for the technical design within the spec.\n- **`references\u002Fspec_format_guide.md`** — Complete template with section-by-section explanations.\n- **`references\u002Fbounded_autonomy_rules.md`** — Full decision matrix for when to stop vs. continue.\n- **`references\u002Facceptance_criteria_patterns.md`** — Pattern library for writing Given\u002FWhen\u002FThen criteria.\n\n---\n\n## Tools\n\n| Script | Purpose | Key Flags |\n|--------|---------|-----------|\n| `spec_generator.py` | Generate spec template from feature name\u002Fdescription | `--name`, `--description`, `--format`, `--json` |\n| `spec_validator.py` | Validate spec completeness (0-100 score) | `--file`, `--strict`, `--json` |\n| `test_extractor.py` | Extract test stubs from acceptance criteria | `--file`, `--framework`, `--output`, `--json` |\n\n```bash\n# Generate a spec template\npython spec_generator.py --name \"User Authentication\" --description \"OAuth 2.0 login flow\"\n\n# Validate a spec\npython spec_validator.py --file specs\u002Fauth.md --strict\n\n# Extract test cases\npython test_extractor.py --file specs\u002Fauth.md --framework pytest --output tests\u002Ftest_auth.py\n```\n","# Spec-Driven Workflow — POWERFUL\n\n## Overview\n\nSpec-driven workflow enforces a single, non-negotiable rule: **write the specification BEFORE you write any code.** Not alongside. Not after. Before.\n\nThis is not documentation. This is a contract. A spec defines what the system MUST do, what it SHOULD do, and what it explicitly WILL NOT do. Every line of code you write traces back to a requirement in the spec. Every test traces back to an acceptance criterion. If it is not in the spec, it does not get built.\n\n### Why Spec-First Matters\n\n1. **Eliminates rework.** 60-80% of defects originate from requirements, not implementation. Catching ambiguity in a spec costs minutes; catching it in production costs days.\n2. **Forces clarity.** If you cannot write what the system should do in plain language, you do not understand the problem well enough to write code.\n3. **Enables parallelism.** Once a spec is approved, frontend, backend, QA, and documentation can all start simultaneously.\n4. **Creates accountability.** The spec is the definition of done. No arguments about whether a feature is \"complete\" — either it satisfies the acceptance criteria or it does not.\n5. **Feeds TDD directly.** Acceptance criteria in Given\u002FWhen\u002FThen format translate 1:1 into test cases. The spec IS the test plan.\n\n### The Iron Law\n\n```\nNO CODE WITHOUT AN APPROVED SPEC.\nNO EXCEPTIONS. NO \"QUICK PROTOTYPES.\" NO \"I'LL DOCUMENT IT LATER.\"\n```\n\nIf the spec is not written, reviewed, and approved, implementation does not begin. Period.\n\n---\n\n## The Spec Format\n\nEvery spec follows this structure. No sections are optional — if a section does not apply, write \"N\u002FA — [reason]\" so reviewers know it was considered, not forgotten.\n\n### Mandatory Sections\n\n| # | Section | Key Rules |\n|---|---------|-----------|\n| 1 | **Title and Metadata** | Author, date, status (Draft\u002FIn Review\u002FApproved\u002FSuperseded), reviewers |\n| 2 | **Context** | Why this feature exists. 2-4 paragraphs with evidence (metrics, tickets). |\n| 3 | **Functional Requirements** | RFC 2119 keywords (MUST\u002FSHOULD\u002FMAY). Numbered FR-N. Each is atomic and testable. |\n| 4 | **Non-Functional Requirements** | Performance, security, accessibility, scalability, reliability — all with measurable thresholds. |\n| 5 | **Acceptance Criteria** | Given\u002FWhen\u002FThen format. Every AC references at least one FR-* or NFR-*. |\n| 6 | **Edge Cases** | Numbered EC-N. Cover failure modes for every external dependency. |\n| 7 | **API Contracts** | TypeScript-style interfaces. Cover success and error responses. |\n| 8 | **Data Models** | Table format with field, type, constraints. Every entity from requirements must have a model. |\n| 9 | **Out of Scope** | Explicit exclusions with reasons. Prevents scope creep during implementation. |\n\n### RFC 2119 Keywords\n\n| Keyword | Meaning |\n|---------|---------|\n| **MUST** | Absolute requirement. Non-conformant without it. |\n| **MUST NOT** | Absolute prohibition. |\n| **SHOULD** | Recommended. Omit only with documented justification. |\n| **MAY** | Optional. Implementer's discretion. |\n\nSee [spec_format_guide.md](references\u002Fspec_format_guide.md) for the complete template with section-by-section examples, good\u002Fbad requirement patterns, and feature-type templates (CRUD, Integration, Migration).\n\nSee [acceptance_criteria_patterns.md](references\u002Facceptance_criteria_patterns.md) for a full pattern library of Given\u002FWhen\u002FThen criteria across authentication, CRUD, search, file upload, payment, notification, and accessibility scenarios.\n\n---\n\n## Bounded Autonomy Rules\n\nThese rules define when an agent (human or AI) MUST stop and ask for guidance vs. when they can proceed independently.\n\n### STOP and Ask When:\n\n1. **Scope creep detected.** The implementation requires something not in the spec. Even if it seems obviously needed, STOP. The spec might have excluded it deliberately.\n\n2. **Ambiguity exceeds 30%.** If you cannot determine the correct behavior from the spec for more than 30% of a given requirement, the spec is incomplete. Do not guess.\n\n3. **Breaking changes required.** The implementation would change an existing API contract, database schema, or public interface. Always escalate.\n\n4. **Security implications.** Any change that touches authentication, authorization, encryption, or PII handling requires explicit approval.\n\n5. **Performance characteristics unknown.** If a requirement says \"MUST complete in \u003C 500ms\" but you have no way to measure or guarantee that, escalate before implementing a guess.\n\n6. **Cross-team dependencies.** If the spec requires coordination with another team or service, confirm the dependency before building against it.\n\n### Continue Autonomously When:\n\n1. **Spec is clear and unambiguous** for the current task.\n2. **All acceptance criteria have passing tests** and you are refactoring internals.\n3. **Changes are non-breaking** — no public API, schema, or behavior changes.\n4. **Implementation is a direct translation** of a well-defined acceptance criterion.\n5. **Error handling follows established patterns** already documented in the codebase.\n\n### Escalation Protocol\n\nWhen you must stop, provide:\n\n```markdown\n## Escalation: [Brief Title]\n\n**Blocked on:** [requirement ID, e.g., FR-3]\n**Question:** [Specific, answerable question — not \"what should I do?\"]\n**Options considered:**\n  A. [Option] — Pros: [...] Cons: [...]\n  B. [Option] — Pros: [...] Cons: [...]\n**My recommendation:** [A or B, with reasoning]\n**Impact of waiting:** [What is blocked until this is resolved?]\n```\n\nNever escalate without a recommendation. Never present an open-ended question. Always give options.\n\nSee `references\u002Fbounded_autonomy_rules.md` for the complete decision matrix.\n\n---\n\n## Workflow — 6 Phases\n\n### Phase 1: Gather Requirements\n\n**Goal:** Understand what needs to be built and why.\n\n1. **Interview the user.** Ask:\n   - What problem does this solve?\n   - Who are the users?\n   - What does success look like?\n   - What explicitly should NOT be built?\n2. **Read existing code.** Understand the current system before proposing changes.\n3. **Identify constraints.** Performance budgets, security requirements, backward compatibility.\n4. **List unknowns.** Every unknown is a risk. Surface them now, not during implementation.\n\n**Exit criteria:** You can explain the feature to someone unfamiliar with the project in 2 minutes.\n\n### Phase 2: Write Spec\n\n**Goal:** Produce a complete spec document following The Spec Format above.\n\n1. Fill every section of the template. No section left blank.\n2. Number all requirements (FR-*, NFR-*, AC-*, EC-*, OS-*).\n3. Use RFC 2119 keywords precisely.\n4. Write acceptance criteria in Given\u002FWhen\u002FThen format.\n5. Define API contracts with TypeScript-style types.\n6. List explicit exclusions in Out of Scope.\n\n**Exit criteria:** The spec can be handed to a developer who was not in the requirements meeting, and they can implement the feature without asking clarifying questions.\n\n### Phase 3: Validate Spec\n\n**Goal:** Verify the spec is complete, consistent, and implementable.\n\nRun `spec_validator.py` against the spec file:\n\n```bash\npython spec_validator.py --file spec.md --strict\n```\n\nManual validation checklist:\n- [ ] Every functional requirement has at least one acceptance criterion\n- [ ] Every acceptance criterion is testable (no subjective language)\n- [ ] API contracts cover all endpoints mentioned in requirements\n- [ ] Data models cover all entities mentioned in requirements\n- [ ] Edge cases cover failure modes for every external dependency\n- [ ] Out of scope is explicit about what was considered and rejected\n- [ ] Non-functional requirements have measurable thresholds\n\n**Exit criteria:** Spec scores 80+ on validator, and all manual checklist items pass.\n\n### Phase 4: Generate Tests\n\n**Goal:** Extract test cases from acceptance criteria before writing implementation code.\n\nRun `test_extractor.py` against the approved spec:\n\n```bash\npython test_extractor.py --file spec.md --framework pytest --output tests\u002F\n```\n\n1. Each acceptance criterion becomes one or more test cases.\n2. Each edge case becomes a test case.\n3. Tests are stubs — they define the assertion but not the implementation.\n4. All tests MUST fail initially (red phase of TDD).\n\n**Exit criteria:** You have a test file where every test fails with \"not implemented\" or equivalent.\n\n### Phase 5: Implement\n\n**Goal:** Write code that makes failing tests pass, one acceptance criterion at a time.\n\n1. Pick one acceptance criterion (start with the simplest).\n2. Make its test(s) pass with minimal code.\n3. Run the full test suite — no regressions.\n4. Commit.\n5. Pick the next acceptance criterion. Repeat.\n\n**Rules:**\n- Do NOT implement anything not in the spec.\n- Do NOT optimize before all acceptance criteria pass.\n- Do NOT refactor before all acceptance criteria pass.\n- If you discover a missing requirement, STOP and update the spec first.\n\n**Exit criteria:** All tests pass. All acceptance criteria satisfied.\n\n### Phase 6: Self-Review\n\n**Goal:** Verify implementation matches spec before marking done.\n\nRun through the Self-Review Checklist below. If any item fails, fix it before declaring the task complete.\n\n---\n\n## Self-Review Checklist\n\nBefore marking any implementation as done, verify ALL of the following:\n\n- [ ] **Every acceptance criterion has a passing test.** No exceptions. If AC-3 exists, a test for AC-3 exists and passes.\n- [ ] **Every edge case has a test.** EC-1 through EC-N all have corresponding test cases.\n- [ ] **No scope creep.** The implementation does not include features not in the spec. If you added something, either update the spec or remove it.\n- [ ] **API contracts match implementation.** Request\u002Fresponse shapes in code match the spec exactly. Field names, types, status codes — all of it.\n- [ ] **Error scenarios tested.** Every error response defined in the spec has a test that triggers it.\n- [ ] **Non-functional requirements verified.** If the spec says \u003C 500ms, you have evidence (benchmark, load test, profiling) that it meets the threshold.\n- [ ] **Data model matches.** Database schema matches the spec. No extra columns, no missing constraints.\n- [ ] **Out-of-scope items not built.** Double-check that nothing from the Out of Scope section leaked into the implementation.\n\n---\n\n## Integration with TDD Guide\n\nSpec-driven workflow and TDD are complementary, not competing:\n\n```\nSpec-Driven Workflow          TDD (Red-Green-Refactor)\n─────────────────────         ──────────────────────────\nPhase 1: Gather Requirements\nPhase 2: Write Spec\nPhase 3: Validate Spec\nPhase 4: Generate Tests  ──→  RED: Tests exist and fail\nPhase 5: Implement       ──→  GREEN: Minimal code to pass\nPhase 6: Self-Review     ──→  REFACTOR: Clean up internals\n```\n\n**The handoff:** Spec-driven workflow produces the test stubs (Phase 4). TDD takes over from there. The spec tells you WHAT to test. TDD tells you HOW to implement.\n\nUse `engineering-team\u002Ftdd-guide` for:\n- Red-green-refactor cycle discipline\n- Coverage analysis and gap detection\n- Framework-specific test patterns (Jest, Pytest, JUnit)\n\nUse `engineering\u002Fspec-driven-workflow` for:\n- Defining what to build before building it\n- Acceptance criteria authoring\n- Completeness validation\n- Scope control\n\n---\n\n## Examples\n\nA complete worked example (Password Reset spec with extracted test cases) is available in [spec_format_guide.md](references\u002Fspec_format_guide.md#full-example-password-reset). It demonstrates all 9 sections, requirement numbering, acceptance criteria, edge cases, and the corresponding pytest stubs generated by `test_extractor.py`.\n\n---\n\n## Anti-Patterns\n\n### 1. Coding Before Spec Approval\n\n**Symptom:** \"I'll start coding while the spec is being reviewed.\"\n**Problem:** The review will surface changes. Now you have code that implements a rejected design.\n**Rule:** Implementation does not begin until spec status is \"Approved.\"\n\n### 2. Vague Acceptance Criteria\n\n**Symptom:** \"The system should work well\" or \"The UI should be responsive.\"\n**Problem:** Untestable. What does \"well\" mean? What does \"responsive\" mean?\n**Rule:** Every acceptance criterion must be verifiable by a machine. If you cannot write a test for it, rewrite the criterion.\n\n### 3. Missing Edge Cases\n\n**Symptom:** Happy path is specified, error paths are not.\n**Problem:** Developers invent error handling on the fly, leading to inconsistent behavior.\n**Rule:** For every external dependency (API, database, file system, user input), specify at least one failure scenario.\n\n### 4. Spec as Post-Hoc Documentation\n\n**Symptom:** \"Let me write the spec now that the feature is done.\"\n**Problem:** This is documentation, not specification. It describes what was built, not what should have been built. It cannot catch design errors because the design is already frozen.\n**Rule:** If the spec was written after the code, it is not a spec. Relabel it as documentation.\n\n### 5. Gold-Plating Beyond Spec\n\n**Symptom:** \"While I was in there, I also added...\"\n**Problem:** Untested code. Unreviewed design. Potential for subtle bugs in the \"bonus\" feature.\n**Rule:** If it is not in the spec, it does not get built. File a new spec for additional features.\n\n### 6. Acceptance Criteria Without Requirement Traceability\n\n**Symptom:** AC-7 exists but does not reference any FR-* or NFR-*.\n**Problem:** Orphaned criteria mean either a requirement is missing or the criterion is unnecessary.\n**Rule:** Every AC-* MUST reference at least one FR-* or NFR-*.\n\n### 7. Skipping Validation\n\n**Symptom:** \"The spec looks fine, let's just start.\"\n**Problem:** Missing sections discovered during implementation cause blocking delays.\n**Rule:** Always run `spec_validator.py --strict` before starting implementation. Fix all warnings.\n\n---\n\n## Cross-References\n\n- **`engineering-team\u002Ftdd-guide`** — Red-green-refactor cycle, test generation, coverage analysis. Use after Phase 4 of this workflow.\n- **`engineering\u002Ffocused-fix`** — Deep-dive feature repair. When a spec-driven implementation has systemic issues, use focused-fix for diagnosis.\n- **`engineering\u002Frag-architect`** — If the feature involves retrieval or knowledge systems, use rag-architect for the technical design within the spec.\n- **`references\u002Fspec_format_guide.md`** — Complete template with section-by-section explanations.\n- **`references\u002Fbounded_autonomy_rules.md`** — Full decision matrix for when to stop vs. continue.\n- **`references\u002Facceptance_criteria_patterns.md`** — Pattern library for writing Given\u002FWhen\u002FThen criteria.\n\n---\n\n## Tools\n\n| Script | Purpose | Key Flags |\n|--------|---------|-----------|\n| `spec_generator.py` | Generate spec template from feature name\u002Fdescription | `--name`, `--description`, `--format`, `--json` |\n| `spec_validator.py` | Validate spec completeness (0-100 score) | `--file`, `--strict`, `--json` |\n| `test_extractor.py` | Extract test stubs from acceptance criteria | `--file`, `--framework`, `--output`, `--json` |\n\n```bash\n# Generate a spec template\npython spec_generator.py --name \"User Authentication\" --description \"OAuth 2.0 login flow\"\n\n# Validate a spec\npython spec_validator.py --file specs\u002Fauth.md --strict\n\n# Extract test cases\npython test_extractor.py --file specs\u002Fauth.md --framework pytest --output tests\u002Ftest_auth.py\n```\n",{"name":5,"description":7},"main","992d25a425dee442a1f6a628d00a4fed33efe839","engineering\u002Fskills\u002Fspec-driven-workflow","https:\u002F\u002Fgithub.com\u002FGongYuanCaiJi\u002Fdsh-claude-skills","https:\u002F\u002Fgithub.com\u002FGongYuanCaiJi","漏洞研究、根因分析、黑箱測試｜做 AI agent 工具｜Vulnerability research, root-cause analysis, AI agent tooling","2026-08-16 04:26:20",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add GongYuanCaiJi\u002Fdsh-claude-skills --skill spec-driven-workflow",{"tool":37,"command":38},"bunx","bunx skills add GongYuanCaiJi\u002Fdsh-claude-skills --skill spec-driven-workflow",{"tool":40,"command":41},"pnpm","pnpm dlx skills add GongYuanCaiJi\u002Fdsh-claude-skills --skill spec-driven-workflow","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FGongYuanCaiJi\u002Fdsh-claude-skills\u002Fblob\u002Fmain\u002Fengineering\u002Fskills\u002Fspec-driven-workflow\u002FSKILL.md",true,[45,51,55,59,65,69],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"references\u002Facceptance_criteria_patterns.md","REFERENCE","参考文档",15278,"https:\u002F\u002Fgithub.com\u002FGongYuanCaiJi\u002Fdsh-claude-skills\u002Fblob\u002Fmain\u002Fengineering\u002Fskills\u002Fspec-driven-workflow\u002Freferences\u002Facceptance_criteria_patterns.md",{"path":52,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":53,"sourceHtmlUrl":54},"references\u002Fbounded_autonomy_rules.md",11607,"https:\u002F\u002Fgithub.com\u002FGongYuanCaiJi\u002Fdsh-claude-skills\u002Fblob\u002Fmain\u002Fengineering\u002Fskills\u002Fspec-driven-workflow\u002Freferences\u002Fbounded_autonomy_rules.md",{"path":56,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":57,"sourceHtmlUrl":58},"references\u002Fspec_format_guide.md",19127,"https:\u002F\u002Fgithub.com\u002FGongYuanCaiJi\u002Fdsh-claude-skills\u002Fblob\u002Fmain\u002Fengineering\u002Fskills\u002Fspec-driven-workflow\u002Freferences\u002Fspec_format_guide.md",{"path":60,"resourceType":61,"resourceTypeDesc":62,"sizeBytes":63,"sourceHtmlUrl":64},"scripts\u002Fspec_generator.py","SCRIPT","脚本",10423,"https:\u002F\u002Fgithub.com\u002FGongYuanCaiJi\u002Fdsh-claude-skills\u002Fblob\u002Fmain\u002Fengineering\u002Fskills\u002Fspec-driven-workflow\u002Fscripts\u002Fspec_generator.py",{"path":66,"resourceType":61,"resourceTypeDesc":62,"sizeBytes":67,"sourceHtmlUrl":68},"scripts\u002Fspec_validator.py",17483,"https:\u002F\u002Fgithub.com\u002FGongYuanCaiJi\u002Fdsh-claude-skills\u002Fblob\u002Fmain\u002Fengineering\u002Fskills\u002Fspec-driven-workflow\u002Fscripts\u002Fspec_validator.py",{"path":70,"resourceType":61,"resourceTypeDesc":62,"sizeBytes":71,"sourceHtmlUrl":72},"scripts\u002Ftest_extractor.py",14890,"https:\u002F\u002Fgithub.com\u002FGongYuanCaiJi\u002Fdsh-claude-skills\u002Fblob\u002Fmain\u002Fengineering\u002Fskills\u002Fspec-driven-workflow\u002Fscripts\u002Ftest_extractor.py",[74,81,88,95,102,109],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":19},"01M7ASG5XZVP67CMMRENYFQWPW","syllabus","Generates a curated supplementary reading list from any course syllabus using Consensus academic search. Grill-me intake (syllabus input format + course audience + year range) plus a grouping forcing-options checkpoint before any search runs — so the reading list matches the course's level and recency need. Parses the syllabus to extract topics and learning outcomes, searches Consensus for recent peer-reviewed papers per topic, and produces a professionally formatted .docx with clickable Consensus links, plain-language summaries calibrated to audience level, and Bloom-higher-order discussion questions tied to course learning goals. Use when the user uploads a syllabus, course outline, or curriculum document and wants supplementary readings (e.g., 'create a reading list from this syllabus', 'find recent papers for my course') — even casual mentions with a syllabus attached should trigger this skill.","https:\u002F\u002Fgithub.com\u002FGongYuanCaiJi\u002Fdsh-claude-skills\u002Fblob\u002Fmain\u002Fresearch\u002Fsyllabus\u002Fskills\u002Fsyllabus\u002FSKILL.md",[],[],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":19},"01M7ASFSGJF6G9KM40S1QJPR57","research","Default entry point for any research request — a hybrid router that classifies the question deterministically and either delegates to a specialist research skill (pulse for trends\u002Fsentiment, grants for NIH funding, litreview for academic literature, syllabus for course reading, patent for prior-art + IP landscape, dossier for entity research) or runs its own plan-decompose-multi-source-search-synthesize-cite fallback workflow when no specialist matches. Always surfaces the routing decision so users can override. Use when the user makes any research request that doesn't obviously match a more-specific specialist skill (e.g., \"research [topic]\", \"look into [topic]\", \"what do we know about [topic]\", \"investigate [topic]\", \"find me information on [topic]\", \"do some research on [topic]\", \"I need to understand [topic]\"). Output is a markdown briefing (default) or .docx document (on request) with full citations and an audit log.","https:\u002F\u002Fgithub.com\u002FGongYuanCaiJi\u002Fdsh-claude-skills\u002Fblob\u002Fmain\u002Fresearch\u002Fresearch\u002Fskills\u002Fresearch\u002FSKILL.md",[],[],{"skillNo":89,"name":90,"nameZh":6,"description":91,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":19},"01M7ASFFNCMS1X5X276VE277KW","pulse","Multi-source recency research skill that takes the pulse of any topic across Reddit, Hacker News, the open web, and optionally X\u002FTwitter within a configurable recent window (default 30 days). Forcing intake clarifies topic specificity, angle (trend\u002Fsentiment\u002Fproblems\u002Fopportunities\u002Fcomparison), time window, and platform scope before searching. Returns a synthesized briefing with citations, engagement metrics, and cross-platform pattern analysis. Use when the user requests multi-source recency intelligence on a topic (e.g., 'pulse on [topic]', 'what's happening with [topic]', 'what are people saying about [topic]', 'current conversation about [topic]', 'take the pulse of [topic]', 'trending: [topic]', 'find me info on [topic]'), and for competitor research, trend discovery, tool comparisons, and audience sentiment analysis.","https:\u002F\u002Fgithub.com\u002FGongYuanCaiJi\u002Fdsh-claude-skills\u002Fblob\u002Fmain\u002Fresearch\u002Fpulse\u002Fskills\u002Fpulse\u002FSKILL.md",[],[],{"skillNo":96,"name":97,"nameZh":6,"description":98,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":99,"categories":100,"keywords":101,"publishedAt":19},"01M7ASF2BM8D9CDRQV1VBV7FV6","patent","Patent prior-art and landscape intelligence skill — not generic patent help. Commits to one of five sub-use-cases via forcing intake (novelty search \u002F freedom-to-operate \u002F competitive landscape \u002F acquisition diligence \u002F litigation prior-art) before any search runs. Searches Google Patents, Espacenet, USPTO, and optionally Lens.org for citation-graph signals. Output is an editable Word document (.docx) with verdict, ranked closest art (claim-text extracted), CPC-class-aware landscape, family-resolved hits, geographic coverage, FTO flags where applicable, strategy recommendations, and full audit log. Use when the user asks for patent searching or analysis (e.g., 'prior art search for [invention]', 'freedom to operate analysis for [product]'). Produces search signal, not legal advice — always recommends consulting a patent attorney before filing or licensing decisions. Trademark, copyright, and trade-secret questions are out of scope.","https:\u002F\u002Fgithub.com\u002FGongYuanCaiJi\u002Fdsh-claude-skills\u002Fblob\u002Fmain\u002Fresearch\u002Fpatent\u002Fskills\u002Fpatent\u002FSKILL.md",[],[],{"skillNo":103,"name":104,"nameZh":6,"description":105,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":106,"categories":107,"keywords":108,"publishedAt":19},"01M7ASERRV1ES4S7QJRTTYWK0H","notebooklm","Browser automation skill for controlling Google's NotebookLM. Use when the user wants anything done in NotebookLM (e.g., 'open NotebookLM', 'check my [name] notebook', 'ask my notebook about X', 'add [source] to NotebookLM', 'generate a Video Overview from my notebook', 'use NotebookLM Studio'). Handles reading and querying notebooks, adding sources (URLs, text, files, YouTube links, synthesized content), generating Studio outputs (Audio\u002FVideo Overviews, Mind Maps, Reports incl. Briefing Doc\u002FStudy Guide\u002FFAQ, Flashcards, Quiz, slide decks, infographics — discover the exact set from the live Studio panel; the UI evolves fast), and creating new notebooks. Requires browser automation environment — fails gracefully when unavailable.","https:\u002F\u002Fgithub.com\u002FGongYuanCaiJi\u002Fdsh-claude-skills\u002Fblob\u002Fmain\u002Fresearch\u002Fnotebooklm\u002Fskills\u002Fnotebooklm\u002FSKILL.md",[],[],{"skillNo":110,"name":111,"nameZh":6,"description":112,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":113,"categories":114,"keywords":115,"publishedAt":19},"01M7ASEANH3H547WQBZ7X8W5CX","litreview","Academic literature orientation skill that searches papers via free keyless APIs (PubMed E-utilities + OpenAlex) by default — with the Consensus MCP as an optional enhancement lane when connected — builds a strategic search plan using PICO (default) or SPIDER \u002F Decomposition \u002F hybrid as fallbacks, and synthesizes findings into a formatted Word (.docx) research guide. Grill-me intake (research question specificity + framework hint + tentative depth) before the recon search; a second forcing checkpoint after Phase 2 confirms framework + sub-areas + depth before searches consume budget. Configurable depth (5\u002F10\u002F20 queries) controls coverage vs. speed. Output is a 'launching pad' — an orientation guide that lets a researcher dive in confidently, not a finished review. Use when the user starts literature-oriented research (e.g., 'litreview on [topic]', 'literature review on [topic]', 'I'm starting a literature review on X', 'I'm writing a paper on X', 'help me research X', 'I'm doing research on X', 'can you help me research X'). Do NOT use for single one-off paper searches wanting a quick list — that's a plain PubMed\u002FOpenAlex (or Consensus) query.","https:\u002F\u002Fgithub.com\u002FGongYuanCaiJi\u002Fdsh-claude-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flitreview\u002Fskills\u002Flitreview\u002FSKILL.md",[],[]]