pair-process-implement

name	pair-process-implement
description	Implements a refined user story task-by-task, via a 5-step cycle per task (context, branch, implementation, quality, commit), and opens one PR when the story completes. Composes /pair-capability-verify-quality, /pair-capability-record-decision.
version	0.4.1
author	Foomakers

/pair-process-implement — Task Implementation

Implement a user story by processing its tasks sequentially. Each task follows a 5-step cycle: context → branch → implementation → quality → commit. The story-level process has 5 phases (0–4): analysis, setup, implementation, PR creation, and post-review merge. Creates a single PR when all tasks are done.

One PR per story: the story lands on ONE branch with ONE PR; subsequent work on the story (further tasks/features) updates that same PR, never a new one unless a human explicitly requests it.

Composed Skills

Skill	Type	Required
/pair-capability-verify-quality	Capability	Yes — invoked at quality validation phase
/pair-capability-record-decision	Capability	Yes — invoked when a decision needs recording
/pair-capability-assess-stack	Capability	Optional — invoked when a new dependency is detected. If not installed, warn and continue.
/pair-capability-verify-adoption	Capability	Optional — invoked before commit to check adoption compliance. If not installed, warn and continue.

Phase 0: Story & Task Analysis (BLOCKING)

No implementation without complete understanding.

Step 0.1: Load Story

1. Check: Is the user story already loaded in this session?
2. Skip: If yes, confirm story ID and move to Step 0.1b.
3. Act: Read the story from the PM tool — resolution: see way-of-working / PM-tool resolution.
   • Understand business value and acceptance criteria.
   • Confirm epic context.
4. Verify: Story is fully loaded. If not → HALT.

Step 0.1b: Activate Story in PM Tool (NEVER SKIP)

1. Check: Is the story already assigned to the current developer AND status is "In Progress"?
2. Skip: If BOTH conditions met, move to Step 0.2.
3. Act: Update the PM tool:
   • Assign the story to the current developer (if not already assigned).
   • Set status to "In Progress" in the PM tool board/project.
4. Verify: Story is assigned and In Progress. If PM tool is inaccessible → warn developer and continue.

Step 0.2: Analyze Tasks

1. Check: Are all tasks in the story readable and complete?
2. Act: Read ALL tasks. For each task, validate it has:
   • Complete task information (ID, parent story, priority, status)
   • Implementation approach (technical design, files, dependencies)
   • Acceptance criteria (deliverable, quality standards, verification)
   • Development workflow (TDD approach if development task, implementation steps)
3. Verify: All tasks are complete and follow the task template. If any task is incomplete → HALT and propose specific task updates.

Step 0.3: Confirm with Developer

Present analysis:

IMPLEMENTATION STATE:
├── Story: [#ID: Title]
├── PM Status: [In Progress ✓ | ⚠️ Not updated — reason]
├── Tasks: [N total — list each with type and status]
├── Task Types: [Development: N, Documentation: N, Configuration: N]
├── Dependencies: [prerequisite stories and their status]
└── Ready: [Yes | No — reason]

Ask: "Ready to proceed with implementation?"

Phase 1: Setup

Step 1.1: Load Technical Context

1. Check: Are adoption files already loaded in this session?
2. Skip: If yes, move to Step 1.2.
3. Act: Read:
   • architecture.md — architectural patterns
   • tech-stack.md — approved libraries and versions
   • way-of-working.md — development process
   • Design Rules — evidence-based do/don't patterns to avoid generating (constraints, not suggestions)
4. Verify: Technical context loaded. If adoption files missing, warn and proceed with guideline defaults.

Step 1.2: Create or Switch to Feature Branch

1. Check: Does a branch for this story already exist? (git branch --list 'feature/#<story-id>-*')

2. Skip: If branch exists, switch to it (git checkout <branch>) and move to Step 1.3.

3. Act: Create branch from main:

   git checkout main && git pull origin main
   git checkout -b feature/#<story-id>-<brief-description>
   

4. Verify: On the correct feature branch.

Step 1.3: Choose Commit Strategy

1. Check: Is this a single-task story?

2. Skip: If single task, set strategy to commit-per-story (one task = one commit). Move to Phase 2.

3. Act: Ask the developer:

   Commit strategy for this story:

   1. Commit per task (recommended) — develop one task, ask dev, commit, update checkbox, next task. Single PR at end.
   2. Commit per story — develop all tasks continuously, then ask dev, commit all, update all checkboxes, single PR.

4. Verify: Strategy is set. Apply consistently for the entire story.

Phase 2: Task-by-Task Implementation

Process tasks sequentially, one at a time. For each task:

Step 2.1: Select Next Task

1. Check: Scan all tasks in dependency order. Find the first task that is not yet completed.

   • A task is "completed" if its checklist item is marked ✅ in the story AND (if commit-per-task) the commit exists on the branch.

2. Skip: If all tasks are completed, move to Phase 3.

3. Act: Set the active task. Update session state:

   ACTIVE TASK:
   ├── Task: [T-N: Title]
   ├── Type: [Development | Documentation | Configuration | Research]
   ├── Mode: [TDD | Direct Implementation]
   └── Phase: [Starting]
   

Step 2.2: Validate Task Completeness

1. Check: Does the active task have all required fields per the task template?
2. Skip: If complete, proceed to Step 2.3.
3. Act: If incomplete → HALT. Report missing fields and propose specific updates.

Step 2.3: Execute Implementation

For Development Tasks (TDD Required):

Follow the TDD discipline rules strictly, and the Design Rules loaded in Step 1.1 — do not generate a new instance of a known do/don't pattern (e.g. god module, static-only namespace class, optional-bag dispatch instead of a discriminated union).

TDD Discipline Rules:

1. New features → add tests autonomously. Write unit tests without asking.
2. Modifying existing tests → ask developer with evidence. Show what changes and why, get approval before modifying any existing test.
3. No code+test changes in the same session. When changing production code, do NOT modify tests until all existing tests pass. Separate RED, GREEN, and REFACTOR into distinct sessions:
   • RED session: Write or modify ONLY test code. Tests MUST fail. No implementation code changes.
   • GREEN session: Write or modify ONLY implementation code. Write minimal code to make tests pass. No test code changes.
   • REFACTOR session: Improve structure without changing behavior. Both test and production code may be cleaned up. All tests must remain green.
4. Every module file must have a corresponding unit test file. 1:1 mapping between source modules and test files.
5. Avoid mocks — prefer in-memory test doubles. Use dependency injection with in-memory implementations (e.g., InMemoryFileSystemService instead of mocking fs).

For Non-Development Tasks (Direct Implementation):

• Documentation: Implement directly following documentation standards.
• Configuration: Apply infrastructure guidelines.
• Research: Document findings and recommendations.

Step 2.4: Check for New Dependencies

1. Check: Did the implementation introduce any new dependency not listed in tech-stack.md?

2. Skip: If no new dependencies, move to Step 2.5.

3. Act: Is /pair-capability-assess-stack installed?

   • Yes: Compose /pair-capability-assess-stack to validate and register the dependency. If /pair-capability-assess-stack rejects (incompatible) → HALT.

   • No: Warn the developer:

     New dependency detected: [package@version]. /pair-capability-assess-stack is not installed — please manually verify against the tech stack and update tech-stack.md.

4. Verify: Dependency is either validated by /pair-capability-assess-stack or acknowledged by developer.

Step 2.5: Check for Decisions

1. Check: Did the implementation introduce any decision not covered by existing ADRs or ADLs?
2. Skip: If no new decisions needed, move to Step 2.6.
3. Act: Ask the developer if a decision record is needed. If yes, compose /pair-capability-record-decision with the appropriate $type (architectural or non-architectural) and $topic.
4. Verify: Decision recorded and adoption files updated.

Step 2.6: Verify Adoption Compliance

1. Check: Is /pair-capability-verify-adoption installed?

2. Skip: If not installed, warn:

   /pair-capability-verify-adoption is not installed — skipping adoption compliance check. Please manually verify code against adoption files. Move to Step 2.7.

3. Act: Compose /pair-capability-verify-adoption with $scope appropriate to the task.

   • Non-conformities reported → resolve via /pair-capability-assess-stack (tech-stack issues) or /pair-capability-record-decision (architectural gaps).

4. Verify: Adoption compliance confirmed or all non-conformities resolved.

Step 2.7: Verify Quality

1. Act: Compose /pair-capability-verify-quality with $scope = all.
2. Verify: All quality gates pass. If any gate fails → HALT. Developer must fix before proceeding.

Step 2.8: Task Completion

1. Check: Is the commit strategy commit-per-task?

2. Skip: If commit-per-story, continue to next task — return to Step 2.1. No inter-task confirmation.

3. Act (BLOCKING): Present task summary and ask developer for confirmation BEFORE committing:

   TASK DONE:
   ├── Task:   T-N — [title]
   ├── Files:  [N added, N modified]
   └── Next:   T-N+1 — [title] (or "PR" if last task)
   

   Ask: "Task T-N done. OK to commit or changes needed?"

   This confirmation is required for EVERY task — commit-per-task exists precisely to give the developer a checkpoint between tasks.

4. Verify: Developer confirms. If changes needed → apply changes, re-run quality (Step 2.7), ask again.

5. Act: Stage and commit following the commit template:

   [#<story-id>] <type>: <task-description>
   
   - <specific changes>
   - Task: T-N — <task title>
   
   Refs: #<story-id>
   

6. Verify: Commit created.

7. Act: Update the PM tool story issue body:

   • Mark the completed task checkbox (- [x] **T-N**) in the Task Breakdown section.
   • Mark any Definition of Done checkboxes that are now factually satisfied by this task's work (e.g., "SKILL.md created", "template validated"). Leave unchecked items that require reviewer confirmation (e.g., "Code reviewed and merged").

8. Check: Is this the last task?

   • Yes: Move to Phase 3 (PR).
   • No: Return to Step 2.1.

Phase 3: Commit (if per-story), Push & PR

Step 3.1: Final Commit (if commit-per-story)

1. Check: Is the commit strategy commit-per-story?

2. Skip: If commit-per-task, all commits already exist. Move to Step 3.2.

3. Act (BLOCKING): Present summary and ask developer for confirmation BEFORE committing:

   ALL TASKS DONE:
   ├── Tasks:  [list all T-N with titles]
   ├── Files:  [N added, N modified]
   └── Action: Commit all changes
   

   Ask: "All tasks done. Ready to commit or changes needed?"

4. Verify: Developer confirms. If changes needed → apply changes, re-run quality, ask again.

5. Act: Stage all changes and commit:

   [#<story-id>] feat: <story-description>
   
   - <summary of all completed tasks>
   - Tasks: T-1, T-2, ..., T-N
   
   Refs: #<story-id>
   

6. Verify: Commit created with all changes.

7. Act: Update the PM tool story issue body:

   • Mark ALL task checkboxes (- [x] **T-N**) in the Task Breakdown section.
   • Mark all Definition of Done checkboxes that are factually satisfied by the implementation. Leave unchecked items that require reviewer confirmation (e.g., "Code reviewed and merged").

Step 3.2: Push Branch

1. Check: Is the branch already pushed and up to date with remote?

2. Skip: If up to date, move to Step 3.3.

3. Act: Push the branch:

   git push -u origin feature/#<story-id>-<description>
   

4. Verify: Branch pushed to remote.

Step 3.3: Confirm PR with Developer

1. Act: Present a summary before creating the PR:

   PR READY:
   ├── Branch:  [feature/#story-id-description]
   ├── Tasks:   [N/N completed]
   ├── Commits: [N commits on branch]
   ├── Quality: [All gates passing]
   └── Title:   [#<story-id>] <type>: <brief description>
   

2. Ask: "Ready to create the PR?"

3. Verify: Developer confirms. If not → wait for developer instructions.

Step 3.4: Create or Update PR

1. Check: Does a PR already exist for this branch?
2. Skip: If PR exists, update its description and move to output.
3. Act: Read the PR template and fill ALL its sections:
   • Title: [#<story-id>] <type>: <brief description>
   • Body: Use the PR template structure exactly. Fill each section:
     • Summary (What Changed + Why): from story statement and implementation
     • Story Context: link to user story issue, list AC coverage
     • Changes Made: list all completed tasks, files added/modified/deleted
     • Testing: test coverage, quality gate results (from /pair-capability-verify-quality output)
   • Omit template sections that do not apply (e.g., Database Changes, API Changes for KB-only PRs) — do not leave unfilled placeholders.
   • Link: Reference the user story issue (Closes #<story-id>)
   • Labels: Apply appropriate labels
4. Act: Mark the PR as ready for review — ensure it is not in draft state. If the PM tool supports review request (e.g., GitHub gh pr ready), mark it explicitly.
5. Verify: PR created, description follows template, PR is ready for review.

Phase 4: Post-Review Merge

After code review approval (typically via /pair-process-review), re-invoke /pair-process-implement to merge and close — see post-review-merge.md for the verify-approval, merge-commit, merge, and parent-cascade steps (Steps 4.1–4.4) plus the completion output.

Output Format

At PR creation (Phase 3):

IMPLEMENTATION COMPLETE:
├── Story:    [#ID: Title]
├── Branch:   [feature/#ID-description]
├── Strategy: [commit-per-task | commit-per-story]
├── Tasks:    [N/N completed]
├── Commits:  [N commits on branch]
├── PR:       [#PR-number — URL]
└── Quality:  [All gates passing]

At merge (Phase 4): see post-review-merge.md.

HALT Conditions

Implementation stops immediately when:

• Story not loaded or incomplete (Phase 0)
• Task specifications incomplete (Step 2.2)
• Quality gate failure (Step 2.7) — developer must fix
• New dependency rejected by /assess-stack (Step 2.4)
• PR template not found (Step 3.4) — cannot create PR without template
• Commit template not found (Step 2.8 / Step 3.1) — cannot commit without template
• PR not approved (Step 4.1) — cannot merge without review approval

On HALT: report the blocker clearly, propose resolution, wait for developer.

Idempotent Re-invocation

See idempotency convention. Re-invoking /pair-process-implement on a partially completed story is safe and expected — per-step:

1. Branch: detects existing branch, switches to it.
2. Commit strategy: if commits already exist on branch, infer strategy from history.
3. Tasks: scans task checklist and git log to identify completed tasks. Skips them.
4. PR: detects existing PR, updates instead of creating duplicate.
5. Quality gates: re-runs all gates (fast if already passing).
6. Merge: if PR exists and is approved, proceeds directly to Phase 4 (merge).

The skill resumes from the first incomplete step — never re-does completed work.

Graceful Degradation

See graceful degradation (PM tool not accessible → ask the developer directly; adoption file missing → proceed with guideline defaults) for the standard scenarios. Additional cases:

• /pair-capability-assess-stack not installed: Warn on new dependency, continue without validation.
• /pair-capability-verify-adoption not installed: Warn, skip adoption compliance check.
• No quality gate command: Fall back to individual checks (lint, test, type check).

Notes

• This skill modifies files and creates git artifacts (branches, commits, PRs).
• Task iteration is sequential — each task completes its full cycle before the next begins.
• The developer can stop between tasks; re-invoke to resume (see idempotency convention).
• Single PR per story regardless of commit strategy.
• Squash happens at merge (Phase 4), not before PR creation. Individual commits are preserved on the branch during review.