Implement task with skills (/implement, /verify-quality, /record-decision)

[rucka]

Resolution

Delivered by PR #107 (merged). Board: Done.

feat: implement task with skills (/implement, /verify-quality, /record-decision).

Story Statement

As a developer implementing a task with AI assistance
I want to invoke /implement which composes /verify-quality and /record-decision as atomic skills, with how-to-10 thinned to an orchestrator
So that the implementation workflow is structured, consistent, and executable — the AI follows the same quality gates and decision recording process every time

Where: dataset/.skills/process/implement/, dataset/.skills/capability/verify-quality/, dataset/.skills/capability/record-decision/, .pair/knowledge/how-to/10-how-to-implement-a-task.md

Epic Context

Parent Epic: Agent Skills in Knowledge Base #97
Status: Refined
Priority: P0 (Must-Have)

Acceptance Criteria

Functional Requirements

1. Given a developer with a user story containing multiple tasks
   When /implement is invoked in Claude Code
   Then the skill iterates through tasks one at a time, following for each task a structured 5-phase process: context setup → branch creation → TDD implementation → quality validation → commit, reading adoption files for project-specific decisions

2. Given /implement starts on a user story
   When the skill begins
   Then it asks the developer to choose the commit strategy: commit per task (one commit per completed task, single PR at story end) or commit per story (all tasks in one commit, single PR at story end). The choice is applied consistently for the entire story.

3. Given all tasks of a user story are completed and committed
   When /implement reaches the final phase
   Then it creates a PR for the story branch following the PR template (collaboration/templates/pr-template.md), linking the user story issue, with a summary of all completed tasks

4. Given /implement creates a commit (either per task or per story)
   When the commit is being authored
   Then the commit message follows the commit template (collaboration/templates/commit-template.md)

5. Given /implement is invoked and some tasks/steps are already completed (e.g. branch already exists, some tasks already committed)
   When the skill evaluates each task and step
   Then it detects the current state, skips already-completed tasks and steps, and resumes from the first missing action (idempotent execution)

6. Given /implement reaches quality validation on a task
   When the task implementation is complete
   Then /verify-quality is composed automatically, checking quality gates defined in quality-assurance/quality-standards/ and adoption

7. Given an implementation introduces an architectural decision not covered by existing ADRs
   When the developer confirms an ADR is needed
   Then /record-decision is invoked as architectural — it produces an ADR file in adoption/tech/adr/YYYY-MM-DD-<topic>.md following the ADR template AND updates the relevant adoption files to reflect the current state of facts

8. Given an implementation introduces a non-architectural decision (e.g. library choice, convention adoption)
   When the developer confirms a decision record is needed
   Then /record-decision is invoked as non-architectural — it produces an ADL entry in adoption/decision-log/YYYY-MM-DD-<topic>.md AND updates the relevant adoption files

9. Given an implementation introduces a new dependency (library, framework, tool) not listed in the tech stack adoption
   When /implement detects the new dependency (or the developer flags it)
   Then /implement composes /assess-stack (from #104) to validate the dependency, check compatibility with current stack, and add it to adoption/tech/tech-stack.md with version. If /assess-stack is not installed, /implement warns the developer to manually verify the dependency against the tech stack and update adoption accordingly.

10. Given /implement reaches quality validation on a task
    When /verify-adoption (from #105) is installed
    Then /implement composes /verify-adoption with appropriate $scope to check code against adoption files before commit. Non-conformities are reported to the developer for resolution (tech-stack → /assess-stack, architectural → /record-decision). If /verify-adoption is not installed, /implement skips adoption compliance checking with a warning.

11. Given how-to-10 is thinned
    When a non-skill assistant reads how-to-10
    Then the file remains a readable standalone document with phase flow, HALT conditions, and WHY context — just without operational procedures

12. Given /verify-quality is invoked independently (not via /implement)
    When called with a file or PR reference
    Then it validates quality gates as a standalone atomic skill, checking only gates not already passing

13. Given /record-decision is invoked and a decision file for the same topic already exists (ADR or ADL)
    When the skill evaluates the current state
    Then it detects the existing file and offers to update it instead of creating a duplicate, and updates the corresponding adoption files accordingly

14. Given /record-decision completes (either new or update)
    When the adoption files are updated
    Then the adoption files reflect the current state of facts for all technical aspects touched by the decision — adoption is the single source of truth for "what we use now", ADR/ADL is the record of "why we decided"

Business Rules

• Idempotent execution (cross-cutting, applies to ALL skills): every step in a skill MUST check current state before acting, and only execute missing actions. Re-invoking a skill on a partially completed workflow resumes from where it left off — never re-does already completed work. This is a fundamental design principle for all skills in this epic.
• Task iteration: /implement processes tasks sequentially, one at a time. Each task goes through the full 5-phase cycle before moving to the next. The developer can stop between tasks and re-invoke later (idempotency ensures correct resume).
• Commit strategy: decided once per story at the start of /implement. Two options:
  • Commit per task: each completed task is committed separately on the story branch. Produces granular git history. Single PR at story end.
  • Commit per story: all tasks are implemented on the story branch, committed together at the end. Single commit, single PR.
  • Default suggestion: commit per task (more granular, easier to review and revert).
• Single PR per story: regardless of commit strategy, /implement creates exactly one PR per user story, at the end when all tasks are done.
• PR template: /implement MUST follow the PR template (collaboration/templates/pr-template.md) when creating the PR. The template defines the PR body structure — /implement fills it with the story summary, completed tasks, and relevant context.
• Commit template: /implement MUST follow the commit template (collaboration/templates/commit-template.md) when creating commits. This applies to both per-task commits and per-story commits.
• Conditional decision recording: /record-decision writes to ONE of two destinations based on the decision type — ADR and ADL are mutually exclusive:
  • Architectural decision → ADR file (adoption/tech/adr/YYYY-MM-DD-<topic>.md) + adoption file(s) update
  • Non-architectural decision → ADL file (adoption/decision-log/YYYY-MM-DD-<topic>.md) + adoption file(s) update
  • Both use the same file naming pattern (YYYY-MM-DD-<topic>.md) for sortability. One file per decision entry.
  • Adoption update is always required regardless of decision type.
• Date-based file naming: both ADR and ADL files use YYYY-MM-DD-<topic>.md naming. One file per decision, sortable by date. Uniform pattern across both directories.
• New dependency validation via /assess-stack: when /implement detects a new dependency not listed in adoption/tech/tech-stack.md, it composes /assess-stack (from #104) to validate and register the dependency with version. /assess-stack is an optional composition — if not installed, /implement warns the developer and continues. This enables incremental adoption (Implement task with skills (/implement, /verify-quality, /record-decision) #99 before Assessment skills (8 assess-* with resolution cascade) #104).
• Adoption compliance via /verify-adoption: /implement optionally composes /verify-adoption (from #105) before commit to check code against adoption files. /verify-adoption detects non-conformities; /implement resolves via /assess-stack (tech-stack) or /record-decision (architectural). /verify-adoption is an optional composition — if not installed, /implement skips adoption checking with a warning. This enables incremental adoption (Implement task with skills (/implement, /verify-quality, /record-decision) #99 before Remaining capability skills + /verify-adoption + /next update + prompt deprecation #105).
• How-to-10 keeps: phase sequence, HALT conditions, TDD session types (RED/GREEN/REFACTOR), approval gates, WHY context
• How-to-10 loses → /implement skill: git branch creation, commit templates, task validation checklists, quality gate procedures, task iteration logic, PR creation
• /verify-quality references quality-assurance/quality-standards/ for universal standards AND reads adoption/tech/way-of-working.md for project-specific quality gate commands (e.g., pnpm quality-gate). Adoption = "what command we run"; quality-standards = "what we check".
• /record-decision follows standalone ADR template (collaboration/templates/adr-template.md) for architectural decisions and standalone ADL template (collaboration/templates/adl-template.md) for non-architectural decisions
• Adoption binding: /implement reads adoption/tech/tech-stack.md, adoption/tech/architecture.md for project context; /record-decision writes to these same files when decisions change
• ADL format and documentation: ADL format, purpose, and usage are documented in #105

Edge Cases and Error Handling

• Missing adoption files: /implement warns and proceeds with guideline defaults; /record-decision creates the adoption file if it doesn't exist
• Quality gate failure: /verify-quality reports failures, /implement HALTs until resolved
• Decision file conflict: /record-decision detects existing file for same topic+date, offers to update or create with incremented suffix
• Adoption file out of sync with ADR/ADL: /record-decision detects inconsistencies between decision records and adoption state, and proposes reconciliation
• Partial completion: re-invoking /implement on a partially completed story resumes from the last incomplete task/step — already-committed tasks are detected and skipped
• Branch already exists: /implement detects existing branch, switches to it instead of failing on create
• Single task story: commit strategy question is skipped — one task, one commit, one PR
• PR already exists: /implement detects existing PR for the story branch, updates it instead of creating a duplicate
• PR template not found: /implement HALTs with error indicating the PR template path is missing
• Commit template not found: /implement HALTs with error indicating the commit template path is missing
• New dependency with /assess-stack not installed: /implement warns developer to manually verify the dependency against the tech stack adoption file. Implementation continues — the warning is informational, not a HALT.
• New dependency with /assess-stack installed: /assess-stack validates compatibility, adds to tech-stack.md with version, writes decision record. If /assess-stack rejects the dependency (incompatible), /implement HALTs and asks developer to resolve.
• Adoption check with /verify-adoption not installed: /implement warns developer to manually verify adoption compliance. Implementation continues — the warning is informational, not a HALT.
• Adoption check with /verify-adoption installed: /verify-adoption checks code against adoption files per scope. Non-conformities reported to developer; /assess-stack resolves tech-stack issues (if installed), /record-decision resolves architectural gaps.

Definition of Done Checklist

Development Completion

• dataset/.skills/process/implement/SKILL.md created with valid frontmatter, idempotent steps, task iteration, commit strategy choice, PR creation following pr-template.md, commit messages following commit-template.md, optional /assess-stack composition, optional /verify-adoption composition
• dataset/.skills/capability/verify-quality/SKILL.md created with valid frontmatter, idempotent checks, reads quality gate command from adoption/tech/way-of-working.md
• dataset/.skills/capability/record-decision/SKILL.md created with valid frontmatter, idempotent checks, conditional write (ADR|ADL + adoption), date-based file naming, references standalone templates
• dataset/.pair/knowledge/guidelines/collaboration/templates/adr-template.md created — standalone ADR template
• dataset/.pair/knowledge/guidelines/collaboration/templates/adl-template.md created — standalone ADL template
• dataset/.pair/adoption/tech/way-of-working.md updated with Quality Gates section (project-specific quality gate command)
• how-to-10 thinned to ~160-180 lines (orchestration only)
• Thinned how-to-10 readable as standalone document
• Skills reference correct guideline and adoption paths
• Every skill step follows check→skip→act→verify pattern (idempotency)
• /record-decision writes decision file (ADR or ADL) + adoption files on every decision
• /implement gracefully handles /assess-stack presence or absence (optional composition)
• /implement gracefully handles /verify-adoption presence or absence (optional composition)
• Code reviewed and merged

Quality Assurance

• /implement invocable in Claude Code — iterates tasks one at a time, follows 5-phase process per task
• /implement asks commit strategy at start and applies it consistently
• /implement creates PR at story completion following collaboration/templates/pr-template.md, linking user story issue
• /implement commit messages follow collaboration/templates/commit-template.md
• /implement re-invoked on partial progress — resumes from correct task/step, skips completed work
• /implement with new dependency + /assess-stack installed → validates and registers dependency
• /implement with new dependency + /assess-stack not installed → warns developer, continues
• /implement with /verify-adoption installed → checks adoption compliance before commit, reports non-conformities
• /implement with /verify-adoption not installed → warns developer, continues
• /verify-quality invocable independently — validates quality gates, skips passing gates
• /record-decision invocable independently — architectural decision produces ADR + updates adoption
• /record-decision invocable independently — non-architectural decision produces ADL + updates adoption
• /record-decision on existing topic — detects existing file, updates instead of duplicating, updates adoption
• ADR and ADL files use YYYY-MM-DD-<topic>.md naming, one file per decision
• Thinned how-to-10 reviewed for standalone readability
• Adoption binding validated: /implement reads project-specific tech decisions

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: L(5)
Confidence Level: High
Sizing Justification: 3 SKILL.md files + how-to thinning + idempotency pattern design + task iteration with commit strategy + PR creation with pr-template.md + commit messages with commit-template.md + /record-decision conditional write (ADR|ADL + adoption) with date-based naming + optional /assess-stack composition + optional /verify-adoption composition. Content is well-defined (how-to-10 analysis shows 65% orchestration / 35% operational split). This is the pattern-setting story — establishes idempotency convention and how-to thinning approach for all subsequent stories.

Sprint Fit Assessment

Sprint Fit: Yes — single sprint
Development Estimate: 3 days (SKILL.md writing with idempotent steps + how-to thinning)
Testing Estimate: 1 day (Claude Code invocation + re-invocation tests + standalone readability review)

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: #98 (skill infrastructure must exist)
Dependent Stories: #100 (reuses /verify-quality and /record-decision)
Optional Composition: #104 (/assess-stack — composed if installed, graceful degradation if not), #105 (/verify-adoption — composed for adoption compliance if installed, graceful degradation if not)

Validation and Testing Strategy

Acceptance Testing

• Invoke /implement on a multi-task story → verify task-by-task iteration
• Verify commit strategy question at start → choose "per task" → verify individual commits
• Verify commit messages follow collaboration/templates/commit-template.md
• Verify PR creation at story end → PR body follows collaboration/templates/pr-template.md, linked to user story issue
• Re-invoke /implement after partial completion (e.g. 2 of 4 tasks done) → verify it resumes from task 3
• Invoke /implement on a single-task story → verify commit strategy is skipped
• Invoke /implement with new dependency + /assess-stack installed → verify /assess-stack composition validates and registers
• Invoke /implement with new dependency + /assess-stack not installed → verify warning, continues without HALT
• Invoke /implement with /verify-adoption installed → verify adoption compliance check before commit, non-conformities reported
• Invoke /implement with /verify-adoption not installed → verify warning, continues without HALT
• Invoke /verify-quality independently → verify quality gate validation, only checks failing gates
• Invoke /record-decision with architectural decision → verify ADR file in adoption/tech/adr/YYYY-MM-DD-<topic>.md + adoption update
• Invoke /record-decision with non-architectural decision → verify ADL file in adoption/decision-log/YYYY-MM-DD-<topic>.md + adoption update
• Invoke /record-decision on existing topic → verify update instead of duplicate
• Read thinned how-to-10 as standalone → verify comprehensibility

Notes

Open questions resolved:

• How-to-10 phase structure: phases stay in how-to as workflow map, operational steps move to skill
• /verify-quality: references quality-assurance directly (quality standards are universal, not project-specific)
• Idempotency: all skill steps are idempotent — check current state, skip completed actions, execute only what's missing. This is a cross-cutting design principle established in this story and applied to all skills in the epic.
• /record-decision conditional write: ADR and ADL are mutually exclusive. Architectural → ADR + adoption. Non-architectural → ADL + adoption. Both use YYYY-MM-DD-<topic>.md naming (one file per decision, sortable by date). Adoption is the single source of truth for current technical state.
• Task iteration: /implement processes tasks one at a time, sequentially. Developer can stop and resume between tasks.
• Commit strategy: developer chooses once per story — commit per task (default, granular) or commit per story (single commit). Single PR per story regardless.
• PR template: /implement follows collaboration/templates/pr-template.md when creating PRs.
• Commit template: /implement follows collaboration/templates/commit-template.md when creating commits.
• ADL documentation: ADL format, purpose, and usage documented in #105.
• /assess-stack composition: /implement composes /assess-stack (#104) when a new dependency is detected during implementation. Optional composition — graceful degradation if /assess-stack is not installed. Enables incremental adoption.
• /verify-adoption composition: /implement composes /verify-adoption (#105) before commit to check code against adoption files. Optional composition — graceful degradation if /verify-adoption is not installed. Non-conformities detected by /verify-adoption are resolved via /assess-stack (tech-stack) or /record-decision (architectural). Enables incremental adoption.

Highest-value story after infrastructure. Pattern-setting for all subsequent how-to thinning, idempotency convention, and conditional decision recording pattern.

Design reference: docs/design/skills-in-knowledge-base.md sections 1, 3, 4

Technical Analysis

Strategy

Extract operational content from how-to-10 (~457 lines → ~160-180 lines). Write 3 SKILL.md files with YAML frontmatter referencing guidelines and adoption files. Each skill's steps are designed as idempotent checkpoints — check state first, act only if needed. This is the pattern-setting story for all subsequent how-to thinning.

Key Flows

/implement Task Iteration:

1. Read user story → extract task list
2. Ask commit strategy (per task or per story) — skip if single task
3. Create/switch to story branch (idempotent)
4. For each task (sequential): context → TDD → optional /assess-stack → optional /verify-adoption → /verify-quality → commit
5. Final commit (if commit-per-story) → create/update PR following pr-template.md

/record-decision Conditional Write:

1. Determine decision type: architectural or non-architectural
2. Check if decision file already exists → update or create
3. Architectural → ADR in adoption/tech/adr/YYYY-MM-DD-<topic>.md + adoption update
4. Non-architectural → ADL in adoption/decision-log/YYYY-MM-DD-<topic>.md + adoption update
5. Verify consistency: decision record ↔ adoption state

Technical Risks

Risk	Impact	Probability	Mitigation Strategy
How-to thinning breaks standalone readability	Medium	Medium	Review thinned how-to as standalone doc before merging
Skill composition not clear to AI	Medium	Low	Explicit composition instructions in /implement frontmatter
Idempotency checks miss edge cases	Medium	Medium	Test re-invocation at each step boundary; document check patterns
ADR/ADL vs adoption state drift	Medium	Medium	/record-decision always writes decision file + adoption; consistency check
Task detection from PM tool unreliable	Medium	Low	Fallback: developer manually lists tasks

Task Breakdown

• T-1: Create /verify-quality SKILL.md (capability skill)
• T-2: Create /record-decision SKILL.md (capability skill)
• T-3: Create /implement SKILL.md (process skill)
• T-4: Thin how-to-10 from ~456 to ~160-180 lines
• T-5: Validate skills and thinned how-to-10 in Claude Code

Dependency Graph

T-1 (/verify-quality) ──┐
                         ├── T-3 (/implement) ── T-4 (thin) ── T-5 (validate)
T-2 (/record-decision) ─┘

AC Coverage

AC	Tasks
AC-1..5 (implement phases, iteration, PR, commit, idempotent)	T-3, T-5
AC-6 (/verify-quality composition)	T-1, T-3
AC-7..8 (ADR/ADL + adoption)	T-2
AC-9..10 (optional /assess-stack, /verify-adoption)	T-3
AC-11 (thinned how-to-10)	T-4
AC-12 (/verify-quality independent)	T-1, T-5
AC-13..14 (existing decision, adoption truth)	T-2

---

T-1: Create /verify-quality SKILL.md (capability skill)

Priority: P0 | Estimated Hours: 3h | Bounded Context: Knowledge Base Management

Summary: Create /verify-quality atomic capability skill that checks quality gates from quality-assurance/quality-standards/.

Type: Documentation

Description: Atomic capability skill. Checks quality gates from quality-assurance/quality-standards/ (universal standards) AND reads project-specific quality gate command from adoption/tech/way-of-working.md (e.g., pnpm quality-gate). Each gate follows check→skip→act→verify pattern. Invocable independently or composed by /implement and /review. Gates not already passing are checked; passing gates are skipped (idempotent). Adoption = "what command we run"; quality-standards = "what we check".

Acceptance Criteria:

• Primary deliverable: SKILL.md with valid YAML frontmatter per agentskills.io spec
• Quality standard: All quality gates covered; idempotent (skips passing gates)
• Integration requirement: Independently invocable AND composable by /implement and /review
• Verification method: Manual Claude Code validation — invoke independently and as composition

Technical Requirements:

• Functionality: Quality gate checking, idempotent skip logic, independent invocation
• Performance: N/A (markdown skill file)
• Security: N/A

Implementation Approach:

• Technical Design: YAML frontmatter + structured markdown with check→skip→act→verify per gate
• Bounded Context & Modules: Knowledge Base Management — dataset/.skills/capability/
• Files to Modify/Create:
  • dataset/.skills/capability/verify-quality/SKILL.md — new capability skill
  • dataset/.pair/adoption/tech/way-of-working.md — add Quality Gates section with project-specific command
• Technical Standards: agentskills.io spec, references quality-assurance/quality-standards/ and adoption/tech/way-of-working.md

Dependencies:

• Technical: Skill infrastructure from Skill infrastructure + navigator (/next) #98
• Tasks: Skill infrastructure + navigator (/next) #98 complete

Implementation Steps:

1. Create directory dataset/.skills/capability/verify-quality/
2. Write YAML frontmatter (name, description, arguments, references)
3. Write quality gate checking logic with check→skip→act→verify pattern
4. Write independent invocation instructions
5. Write composition interface (how /implement and /review compose this skill)
6. Update adoption/tech/way-of-working.md to add Quality Gates section declaring the project-specific command

Testing Strategy:

• Unit Tests: N/A (markdown skill)
• Manual Testing: Invoke independently in Claude Code; verify gate skip logic; verify adoption reading

Notes: First capability skill — sets the pattern for all subsequent atomic skills. Quality gate command is adoption-driven (project-specific), quality standards are universal.

---

T-2: Create /record-decision SKILL.md (capability skill)

Priority: P0 | Estimated Hours: 4h | Bounded Context: Knowledge Base Management

Summary: Create /record-decision atomic capability skill with conditional write (ADR or ADL) + adoption update.

Type: Documentation

Description: Conditional write skill: architectural → ADR (adoption/tech/adr/YYYY-MM-DD-<topic>.md) + adoption update; non-architectural → ADL (adoption/decision-log/YYYY-MM-DD-<topic>.md) + adoption update. Mutually exclusive — never both. Existing decision detection (same topic+date → offer update instead of duplicate). Date-based naming (YYYY-MM-DD-<topic>.md). Adoption files always updated regardless of decision type — adoption is single source of truth for "what we use now", ADR/ADL is "why we decided". References standalone ADR template (collaboration/templates/adr-template.md) and standalone ADL template (collaboration/templates/adl-template.md).

Acceptance Criteria:

• Primary deliverable: SKILL.md with valid YAML frontmatter
• Quality standard: Architectural → ADR + adoption; non-architectural → ADL + adoption; mutually exclusive
• Integration requirement: Independently invocable AND composable by /implement and /review
• Verification method: Manual validation — architectural decision, non-architectural decision, existing topic detection

Technical Requirements:

• Functionality: Conditional write (ADR|ADL), adoption update, existing decision detection, date-based naming
• Performance: N/A
• Security: N/A

Implementation Approach:

• Technical Design: Decision type routing, file existence check, template-driven writing, adoption update
• Bounded Context & Modules: Knowledge Base Management — dataset/.skills/capability/
• Files to Modify/Create:
  • dataset/.skills/capability/record-decision/SKILL.md — new capability skill
  • dataset/.pair/knowledge/guidelines/collaboration/templates/adr-template.md — new standalone ADR template
  • dataset/.pair/knowledge/guidelines/collaboration/templates/adl-template.md — new standalone ADL template
• Technical Standards: Standalone ADR/ADL templates in collaboration/templates/, date-based naming

Dependencies:

• Technical: Skill infrastructure from Skill infrastructure + navigator (/next) #98
• Tasks: Skill infrastructure + navigator (/next) #98 complete

Implementation Steps:

1. Create standalone adr-template.md in collaboration/templates/
2. Create standalone adl-template.md in collaboration/templates/
3. Create directory dataset/.skills/capability/record-decision/
4. Write YAML frontmatter (name, description, arguments including decision type)
5. Write decision type routing logic (architectural vs non-architectural)
6. Write existing decision detection logic
7. Write ADR file creation/update logic referencing adr-template.md
8. Write ADL file creation/update logic referencing adl-template.md
9. Write adoption file update logic
10. Write consistency verification (decision record ↔ adoption state)

Testing Strategy:

• Unit Tests: N/A (markdown skill)
• Manual Testing: Architectural decision → ADR; non-architectural → ADL; existing topic detection

Notes: ADR and ADL are mutually exclusive. Adoption is always updated. Date-based naming: YYYY-MM-DD-<topic>.md.

---

T-3: Create /implement SKILL.md (process skill)

Priority: P0 | Estimated Hours: 6h | Bounded Context: Knowledge Base Management

Summary: Create /implement process skill — pattern-setting for the entire epic, with TDD discipline rules.

Type: Documentation

Description: Task iteration (sequential), commit strategy (per-task/per-story), 5-phase TDD cycle, PR creation following pr-template.md, commits following commit-template.md. Composes /verify-quality + /record-decision (required). Optional: /assess-stack (#104) + /verify-adoption (#105) with graceful degradation. Every step follows check→skip→act→verify pattern.

TDD Discipline Rules (must be explicitly encoded in the skill):

1. New features → add tests autonomously (AI adds unit tests without asking)
2. Modifying existing tests → ask dev with evidence (show what changes and why, ask approval)
3. No code+test changes in same session (when changing production code, tests MUST NOT be modified until all existing tests pass)
4. Every module file must have corresponding unit test file (1:1 mapping)
5. Avoid mocks — prefer in-memory test doubles (use DI with in-memory implementations like InMemoryFileSystemService)

Acceptance Criteria:

• Primary deliverable: SKILL.md with valid frontmatter, task iteration, commit strategy, TDD discipline rules
• Quality standard: All 5 TDD discipline rules explicitly encoded; idempotent re-invocation works
• Integration requirement: Composes /verify-quality + /record-decision; optional /assess-stack + /verify-adoption
• Verification method: Manual validation — multi-task story, partial re-invocation, single-task story

Technical Requirements:

• Functionality: Task iteration, commit strategy, PR creation, TDD rules, optional compositions
• Performance: N/A
• Security: N/A

Implementation Approach:

• Technical Design: Structured 5-phase process with idempotent checkpoints, composition instructions
• Bounded Context & Modules: Knowledge Base Management — dataset/.skills/process/
• Files to Modify/Create:
  • dataset/.skills/process/implement/SKILL.md — new process skill
• Technical Standards: Follows pr-template.md, commit-template.md, check→skip→act→verify

Dependencies:

• Technical: /verify-quality (T-1), /record-decision (T-2)
• Tasks: T-1, T-2

Implementation Steps:

1. Create directory dataset/.skills/process/implement/
2. Write YAML frontmatter (name, description, composed skills, optional compositions)
3. Write commit strategy choice logic (per-task vs per-story)
4. Write task iteration logic (sequential, idempotent)
5. Write 5-phase process per task (context → branch → TDD → quality → commit)
6. Write TDD discipline rules section
7. Write optional /assess-stack composition with graceful degradation
8. Write optional /verify-adoption composition with graceful degradation
9. Write PR creation logic following pr-template.md
10. Write idempotent re-invocation logic (detect partial progress, resume)

Testing Strategy:

• Unit Tests: N/A (markdown skill)
• Manual Testing: Multi-task story, partial re-invocation, single-task story, optional compositions

Notes: Pattern-setting skill for the entire epic. Establishes idempotency convention, how-to thinning approach, and TDD discipline rules for all subsequent stories.

---

T-4: Thin how-to-10 from ~456 to ~160-180 lines

Priority: P0 | Estimated Hours: 4h | Bounded Context: Knowledge Base Management

Summary: Remove operational content from how-to-10, keeping orchestration structure as standalone document.

Type: Documentation

Description: Keep: overview, session state, core principles, phase flow (workflow map), HALT conditions, TDD session types, approval gates, references. Remove (now in skills): git branch creation, commit templates, task validation checklists, implementation steps, task iteration logic, commit strategy, PR creation, quality gates, decision recording. The thinned how-to must remain readable as a standalone document for non-skill assistants.

Acceptance Criteria:

• Primary deliverable: how-to-10 thinned to ~160-180 lines
• Quality standard: Phase flow preserved; HALT conditions preserved; standalone readable
• Integration requirement: Non-skill assistants can still follow the how-to
• Verification method: Manual readability review

Technical Requirements:

• Functionality: Orchestration structure preserved, operational details removed
• Performance: N/A
• Security: N/A

Implementation Approach:

• Technical Design: Remove operational sections, preserve workflow map and HALT conditions
• Bounded Context & Modules: Knowledge Base Management — .pair/knowledge/how-to/
• Files to Modify/Create:
  • .pair/knowledge/how-to/10-how-to-implement-a-task.md — thin from ~456 to ~160-180 lines
• Technical Standards: Standalone readability for non-skill assistants

Dependencies:

• Technical: /implement skill must exist (T-3) to receive the operational content
• Tasks: T-3

Implementation Steps:

1. Read current how-to-10, identify operational vs orchestration sections
2. Remove git branch creation, commit templates, task validation checklists
3. Remove implementation steps, task iteration logic, commit strategy
4. Remove PR creation, quality gates, decision recording procedures
5. Verify remaining content (~160-180 lines) has phase flow, HALT conditions, TDD session types
6. Review as standalone document for readability

Testing Strategy:

• Unit Tests: N/A
• Manual Testing: Standalone readability review

Notes: Pattern-setting for all how-to thinning. The thinned file must stand alone.

---

T-5: Validate skills and thinned how-to-10 in Claude Code

Priority: P0 | Estimated Hours: 2h | Bounded Context: Knowledge Base Management

Summary: End-to-end validation of all skills and thinned how-to-10 in Claude Code.

Type: Testing

Description: Validate: /implement on multi-task story (task iteration, commit strategy, PR); re-invoke partial (resumes correctly); /verify-quality independently (checks only failing gates); /record-decision architectural + non-architectural; thinned how-to-10 standalone readability. Test optional compositions: /implement with /assess-stack not installed (warns, continues), /implement with /verify-adoption not installed (warns, continues).

Acceptance Criteria:

• Primary deliverable: All skills invocable and producing correct output
• Quality standard: Re-invocation resumes correctly; optional compositions degrade gracefully
• Integration requirement: All skills work in Claude Code environment
• Verification method: Manual Claude Code validation for all scenarios

Technical Requirements:

• Functionality: All skills invocable, idempotent, correct output
• Performance: N/A
• Security: N/A

Implementation Approach:

• Technical Design: Manual validation in Claude Code
• Bounded Context & Modules: Knowledge Base Management
• Files to Modify/Create: None (validation only)
• Technical Standards: All scenarios from AC must pass

Dependencies:

• Technical: All skills and thinned how-to must exist
• Tasks: T-4, Skill infrastructure + navigator (/next) #98 complete

Implementation Steps:

1. Invoke /implement on multi-task story → verify task iteration and commit strategy
2. Re-invoke /implement after partial completion → verify resume
3. Invoke /verify-quality independently → verify gate checking
4. Invoke /record-decision with architectural decision → verify ADR + adoption
5. Invoke /record-decision with non-architectural decision → verify ADL + adoption
6. Test /implement without /assess-stack installed → verify warning
7. Test /implement without /verify-adoption installed → verify warning
8. Read thinned how-to-10 → verify standalone readability

Testing Strategy:

• Manual Testing: All scenarios listed above

Notes: Final validation before story completion.

---

Refinement Date: 2026-02-08
Review and Approval: Approved (2026-02-09)