name	implementation-phase
description	Standard Operating Procedure for /implement phase. Covers TDD workflow, anti-duplication checks, task execution, and continuous testing.
allowed-tools	Read, Write, Edit, Grep, Glob, Bash

Implementation Phase: Standard Operating Procedure

Training Guide: Step-by-step procedures for executing the /implement command with strict TDD discipline and anti-duplication focus.

Supporting references:

reference.md - TDD workflow, anti-duplication checklist, common blockers
examples.md - Good implementations (tests first) vs bad (tests after)
scripts/batch-validator.sh - Validates multiple tasks at once

Phase Overview

Purpose: Execute tasks from tasks.md using Test-Driven Development, preventing code duplication, and maintaining high quality through continuous testing.

Inputs:

specs/NNN-slug/tasks.md - Task breakdown (20-30 tasks)
specs/NNN-slug/plan.md - Implementation plan
Reuse strategy from planning phase

Outputs:

Implemented code (models, services, API endpoints, UI components)
Test suites (unit, integration, component, E2E)
Updated tasks.md (task statuses)
Updated workflow-state.yaml

Expected duration: Variable (2-10 days depending on feature complexity)

Prerequisites

Environment checks:

Tasks phase completed (tasks.md exists with 20-30 tasks)
Plan phase completed (plan.md exists)
Development environment set up
Test framework configured
Git working tree clean

Knowledge requirements:

TDD workflow (RED → GREEN → REFACTOR)
Anti-duplication strategies
Code review checklist
Testing best practices

Execution Steps

Step 1: Review Task List and Dependencies

Actions:

Read tasks.md to understand:
- Total task count and estimated duration
- Task dependencies and sequencing
- Critical path (longest dependency chain)
- Parallel work opportunities
Identify starting tasks:
- Tasks with no dependencies
- Foundation tasks (database, models, config)
- Can execute multiple foundation tasks in parallel

Quality check: Do you understand which tasks to start with?

Step 2: Execute Tasks Using TDD Workflow

For EVERY task, follow strict TDD process:

RED Phase: Write Failing Test

Actions:

Read task acceptance criteria
Write test cases BEFORE any implementation
Run tests → verify they FAIL (RED)
Commit failing tests

Example:

# Task 8: Write unit tests for StudentProgressService

# 1. Create test file
touch api/app/tests/services/test_student_progress_service.py

# 2. Write test cases
# (Write 5 test cases covering happy path + edge cases)

# 3. Run tests → expect failures
pytest api/app/tests/services/test_student_progress_service.py
# Expected: 5 failed, 0 passed ✓

# 4. Commit
git add api/app/tests/services/test_student_progress_service.py
git commit -m "test: add failing tests for StudentProgressService

Task 8: Write unit tests for StudentProgressService
- calculateProgress() tests (3 cases)
- getRecentActivity() tests (2 cases)
All tests currently failing (RED phase)
"

Quality check: Tests fail for the right reason (not implemented yet, not syntax errors).

GREEN Phase: Make Tests Pass

Actions:

Write minimal code to make tests pass
Run tests frequently → work toward GREEN
Stop when all tests pass
Commit working code

Anti-duplication checklist BEFORE writing code:

Search for similar functions in codebase
Review reuse strategy from plan.md
Check for base classes to extend
Look for utility functions to reuse

Example:

# Task 9: Implement StudentProgressService

# 1. Check for code reuse opportunities
grep -r "def calculate" api/app/services/*.py
grep -r "BaseService" api/app/services/*.py

# 2. Implement service (reusing BaseService pattern)
# (Write StudentProgressService class)

# 3. Run tests → work toward passing
pytest api/app/tests/services/test_student_progress_service.py
# First run: 3 failed, 2 passed
# Second run: 1 failed, 4 passed
# Final run: 0 failed, 5 passed ✓

# 4. Commit
git add api/app/services/student_progress_service.py
git commit -m "feat: implement StudentProgressService

Task 9: Implement StudentProgressService
- calculateProgress() method
- getRecentActivity() method
- Reuses BaseService pattern
All 5 tests passing (GREEN phase)
"

Quality check: All tests pass, no code duplication, follows existing patterns.

REFACTOR Phase: Clean Up While Keeping Tests Green

Actions:

Improve code quality without changing behavior
Run tests after EACH refactor → stay GREEN
Extract common logic to utilities
Add type hints, improve naming
Commit refactored code

Refactoring checklist:

Remove code duplication
Extract magic numbers to constants
Improve variable/function names
Add type hints
Add docstrings
Simplify complex conditionals

Example:

# Task 10: Refactor StudentProgressService

# 1. Extract common calculation logic
# Before: completion_rate = len(completed) / len(total)
# After: completion_rate = calculate_percentage(completed, total)

# 2. Run tests after each change
pytest api/app/tests/services/test_student_progress_service.py
# Still: 0 failed, 5 passed ✓

# 3. Commit refactor
git add api/app/services/student_progress_service.py api/app/utils/math.py
git commit -m "refactor: extract percentage calculation to utility

Task 10: Refactor StudentProgressService
- Extracted calculate_percentage() to utils/math.py
- Added type hints to all methods
- Improved variable names (comp_rate → completion_rate)
All tests still passing (REFACTOR phase)
"

Quality check: Tests still pass, code is cleaner, no behavior changes.

Step 3: Update Task Status

Actions: After completing each task:

Mark task as complete in tasks.md:

### Task 9: Implement StudentProgressService ✅

**Status**: Completed
**Completion date**: 2025-10-21
**Actual time**: 6 hours (estimated: 6-8 hours)

**Acceptance criteria**:
- [x] All 5 unit tests from Task 8 pass
- [x] No code duplication (reuses BaseService)
- [x] Follows existing service patterns
- [x] Type hints on all methods

Commit task status update:

git add specs/NNN-slug/tasks.md
git commit -m "chore: mark Task 9 as complete"

Quality check: Task marked complete only when ALL acceptance criteria met.

Step 4: Continuous Anti-Duplication Checks

Before implementing any new function/class, run these checks:

Search for similar code:

# Search by function name pattern
grep -r "def calculate" api/app/**/*.py

# Search by purpose keywords
grep -r "completion.*rate" api/app/**/*.py

# Search in plan.md for reuse strategy
grep "Reuse Strategy" specs/NNN-slug/plan.md

If similar code exists:
- Extract to shared utility module
- Update existing code to use utility
- Document reuse in commit message
If creating new reusable pattern:
- Place in appropriate shared location (utils/, shared/, common/)
- Add unit tests for utility
- Document in plan.md reuse strategy

Quality check: No duplicate logic, high reuse rate (≥60% for standard features).

Step 5: Run Tests Continuously

Test frequency guidelines:

After every code change (TDD discipline):

# Run specific test file
pytest api/app/tests/services/test_student_progress_service.py

# Run with coverage
pytest --cov=api/app/services api/app/tests/services/

After completing each task:

# Run all tests in category
pytest api/app/tests/services/  # All service tests
pytest api/app/tests/routes/    # All API tests
npm test src/components/        # All component tests

Before committing:

# Run full test suite
pytest
npm test

# Check coverage
pytest --cov=api --cov-report=term-missing
npm test -- --coverage

Quality check: All tests pass before committing, coverage ≥80% for business logic.

Step 6: Handle Blocked Tasks

If task is blocked:

Identify blocker:
- Missing dependency (another task not complete)?
- Unclear requirement (needs clarification)?
- Technical issue (environment, library, etc.)?

Document blocker in tasks.md:

### Task 15: Implement Progress API Endpoint

**Status**: Blocked
**Blocked by**: Task 9 (StudentProgressService not complete)
**Blocked date**: 2025-10-21

Move to next task:
- Find tasks with satisfied dependencies
- Work on parallel path
- Return to blocked task when unblocked

Quality check: Blocked tasks documented, alternative tasks identified.

Step 7: Integration Testing

After completing related tasks, run integration tests:

Example (after API endpoint implemented):

# Task 16 complete → run integration tests
pytest api/app/tests/integration/test_student_progress_api.py

# Expected results:
# - 200 response with valid student ID ✓
# - 404 response with invalid ID ✓
# - 403 response without auth ✓
# - 400 response with invalid params ✓
# - Response time <500ms ✓

Quality check: All integration tests pass, response times meet targets.

Step 8: UI Component Testing (if HAS_UI=true)

After implementing UI components, run component tests:

Example:

# Task 23 complete → run component tests
npm test src/pages/ProgressDashboard.test.tsx

# Expected results:
# - Renders loading state ✓
# - Renders chart with data ✓
# - Handles error state ✓
# - Date filter works ✓
# - Keyboard navigation works ✓

# Run Lighthouse for accessibility
npx lighthouse http://localhost:3000/progress --only-categories=accessibility
# Expected: Score ≥95

Quality check: All component tests pass, accessibility score ≥95.

Step 9: End-to-End Testing

After completing all implementation tasks, run E2E tests:

Example:

# All tasks 1-26 complete → run E2E tests
npx playwright test e2e/progress-dashboard.spec.ts

# Expected user flow:
# 1. User logs in ✓
# 2. Navigates to student list ✓
# 3. Clicks "View Progress" ✓
# 4. Dashboard loads ✓
# 5. Filters by 7-day period ✓
# 6. Chart updates ✓

Quality check: Top 3 user journeys work end-to-end.

Step 10: Code Review Checklist

Before marking implementation phase complete, review:

Code quality:

No code duplication
Follows existing patterns
Type hints on all functions
Docstrings on public APIs
No magic numbers (use constants)
Meaningful variable names

Testing:

Test coverage ≥80% for business logic
All unit tests pass
All integration tests pass
All component tests pass (if HAS_UI)
E2E tests pass

Performance:

API response times <500ms (95th percentile)
Database queries optimized (indexes added)
No N+1 query problems

Security:

Authentication/authorization implemented
Input validation on all endpoints
No SQL injection vulnerabilities
No XSS vulnerabilities (if HAS_UI)

Accessibility (if HAS_UI):

Lighthouse score ≥95
Keyboard navigation works
Screen reader compatible (ARIA labels)

Quality check: All checklist items satisfied.

Step 11: Final Validation

Actions:

Run full test suite:

# Backend tests
pytest --cov=api --cov-report=term-missing

# Frontend tests
npm test -- --coverage

# E2E tests
npx playwright test

Verify all tasks complete:

grep "Status: Completed" specs/NNN-slug/tasks.md | wc -l
# Expected: 28 (all tasks)

Update workflow state:

# Update workflow-state.yaml
currentPhase: implementation
status: completed
completedAt: 2025-10-21T14:30:00Z

Quality check: All tests pass, all tasks complete, workflow state updated.

Step 12: Commit Implementation

Actions:

git add .
git commit -m "feat: complete implementation for <feature-name>

Completed 28 tasks:
- Foundation: 3 tasks ✓
- Data layer: 4 tasks ✓
- Business logic: 6 tasks ✓
- API layer: 6 tasks ✓
- UI layer: 6 tasks ✓
- Testing: 3 tasks ✓

Test results:
- Unit tests: 45 passed
- Integration tests: 12 passed
- Component tests: 18 passed
- E2E tests: 3 passed
- Coverage: 87%

🤖 Generated with [Claude Code](https://claude.com/claude-code)
"

Quality check: Implementation committed with comprehensive summary.

Common Mistakes to Avoid

🚫 Implementation Without Tests (Skipping RED Phase)

Impact: Unverified code, regression risk, poor test coverage

Bad workflow:

1. Implement StudentProgressService
2. Write tests afterward (if at all)
Result: Tests don't catch real bugs, coverage gaps

Correct TDD workflow:

1. Write failing tests (RED)
2. Implement to pass tests (GREEN)
3. Refactor while tests pass (REFACTOR)
Result: High confidence, comprehensive coverage

Prevention:

ALWAYS write test task before implementation task
Commit failing tests before any implementation
Run tests continuously (after every small change)

🚫 Duplicate Code Written

Impact: Technical debt, maintenance burden, inconsistent behavior

Scenario:

Task: Implement calculateCompletion() for student progress
Action: Writes new function from scratch
Existing: Similar calculateProgress() exists in 3 other modules
Result: 4th duplicate implementation

Prevention:

Search codebase BEFORE implementing anything new
Review reuse strategy from plan.md
Extract common logic to shared utilities
Target: ≥60% code reuse rate

Anti-duplication checklist:

# Before implementing, search for similar code
grep -r "def calculate.*completion" api/
grep -r "completion.*rate" api/

# Check plan.md reuse strategy
grep "Reuse Strategy" specs/NNN-slug/plan.md

🚫 Tests Written After Code

Impact: Tests don't catch real bugs, false confidence

Why it's bad:

Tests designed to pass existing code (not verify behavior)
Miss edge cases that TDD would catch
Can't refactor confidently

Prevention: Enforce RED → GREEN → REFACTOR discipline

🚫 Large Commits Without Context

Impact: Hard to review, hard to revert, unclear history

Bad commit:

git commit -m "implement feature"
# Changed: 15 files, +2000 lines, -500 lines

Good commits (small, focused):

git commit -m "test: add failing tests for StudentProgressService (Task 8)"
# Changed: 1 file, +85 lines

git commit -m "feat: implement StudentProgressService (Task 9)"
# Changed: 1 file, +120 lines

git commit -m "refactor: extract percentage calculation to utility (Task 10)"
# Changed: 2 files, +15 lines, -10 lines

Prevention: Commit after each task (or even more frequently)

🚫 Skipping Tests Before Committing

Impact: Broken code committed, CI fails, blocks team

Prevention:

# Pre-commit hook (add to .git/hooks/pre-commit)
#!/bin/bash
pytest
npm test
if [ $? -ne 0 ]; then
  echo "Tests failed. Commit aborted."
  exit 1
fi

🚫 Ignoring Blocked Tasks

Impact: Tasks forgotten, feature incomplete

Prevention:

Document blockers explicitly in tasks.md
Set reminders to check blocked tasks
Escalate blockers that can't be resolved quickly

Best Practices

✅ TDD Workflow Example

Perfect TDD execution:

## Task 8-10: StudentProgressService (TDD Triplet)

### Task 8: Write Tests (RED)
1. Create test file with 5 test cases
2. Run tests → all fail (expected)
3. Commit: "test: add failing tests for StudentProgressService"

### Task 9: Implement (GREEN)
1. Check for code reuse opportunities (BaseService, utilities)
2. Write minimal code to pass tests
3. Run tests frequently → work toward all passing
4. Commit: "feat: implement StudentProgressService"

### Task 10: Refactor (REFACTOR)
1. Extract common logic to utilities
2. Add type hints and docstrings
3. Improve names and structure
4. Run tests after EACH change → stay green
5. Commit: "refactor: extract percentage calculation"

Result: High confidence, clean code, comprehensive tests

✅ Anti-Duplication Search Pattern

Before writing ANY new function:

# 1. Search by name pattern
grep -r "def calculate" api/app/**/*.py

# 2. Search by purpose
grep -r "completion.*rate" api/

# 3. Search by similar functionality
grep -r "percentage" api/app/utils/*.py

# 4. Check plan.md reuse strategy
grep -A 10 "Existing patterns to leverage" specs/NNN-slug/plan.md

# 5. If found → reuse or extract
# If not found → implement and document as new reusable pattern

✅ Continuous Testing Cadence

Test at multiple levels:

When	What to Run	Why
After each small change	Single test file	Immediate feedback, stay in flow
After completing task	Test category (all service tests)	Verify task complete, no regressions
Before committing	Full test suite	Ensure nothing broken
Before PR	Full suite + E2E + coverage	Ready for review

✅ Commit Message Template

Use consistent format:

<type>: <short summary> (Task N)

<detailed description>
- Bullet point 1
- Bullet point 2

<test results or metrics>

Types:

test: - Test file additions/changes
feat: - New feature implementation
refactor: - Code cleanup without behavior change
fix: - Bug fix
chore: - Task status update, tooling

Example:

feat: implement GET /api/v1/students/{id}/progress (Task 16)

Implemented API endpoint for student progress dashboard.
- Route in routes/students.py
- Authentication with @require_teacher
- Validation of student_id and period params
- Calls StudentProgressService
- Returns JSON per OpenAPI schema
- Error handling (404, 403, 400)

Test results: All 5 integration tests passing
Response time: 287ms (95th percentile, 500 lessons) ✓

Phase Checklist

Pre-phase checks:

Tasks phase completed (tasks.md exists)
Plan phase completed (plan.md exists)
Development environment set up
Test framework configured
Git working tree clean

During phase (for EACH task):

RED: Write failing tests first
GREEN: Implement to pass tests
REFACTOR: Clean up while staying green
Anti-duplication check performed
Tests run and passing
Task status updated in tasks.md
Changes committed

Post-phase validation:

All tasks complete (20-30 tasks)
All tests pass (unit + integration + component + E2E)
Test coverage ≥80% for business logic
Code review checklist satisfied
No code duplication
Performance targets met
Security checklist satisfied
Accessibility score ≥95 (if HAS_UI)
Implementation committed
workflow-state.yaml updated

Quality Standards

Implementation quality targets:

Test coverage: ≥80% for business logic
Code reuse rate: ≥60%
TDD adherence: 100% (all tests before implementation)
Code duplication: <5%
Performance: API <500ms, UI FCP <1.5s
Accessibility: Lighthouse ≥95 (if HAS_UI)

What makes good implementation:

Strict TDD discipline (RED → GREEN → REFACTOR)
High code reuse (leverages existing patterns)
Comprehensive test coverage (≥80%)
Clean, readable code (type hints, docstrings, good names)
No duplication (<5%)
Meets performance targets

What makes bad implementation:

Tests after code (or no tests)
Code duplication (reinventing wheels)
Poor test coverage (<60%)
Unclear code (no types, cryptic names)
Performance issues (slow queries, heavy renders)
Accessibility failures (if HAS_UI)

Completion Criteria

Phase is complete when:

All pre-phase checks passed
All tasks completed (100%)
All tests passing (unit + integration + component + E2E)
Code review checklist satisfied
Implementation committed
workflow-state.yaml shows currentPhase: implementation and status: completed

Ready to proceed to next phase (/optimize or /ship):

Feature works end-to-end
All acceptance criteria met
Test coverage ≥80%
No critical issues

Troubleshooting

Issue: Tests fail unexpectedly Solution: Run tests in isolation, check for test pollution, verify test fixtures, review test output carefully

Issue: Can't find code to reuse Solution: Use scripts/verify-reuse.sh, search with broader keywords, review plan.md reuse strategy, ask for code review

Issue: Task blocked by dependency Solution: Document blocker in tasks.md, work on parallel tasks, escalate if blocker can't be resolved

Issue: Performance targets not met Solution: Profile code, add database indexes, optimize queries, implement caching, review plan.md performance strategy

Issue: Test coverage below 80% Solution: Identify untested paths with coverage report, add missing test cases, focus on business logic

This SOP guides the implementation phase. Refer to reference.md for TDD details and examples.md for code patterns.

implementation-phase

Install Skill

SKILL.md

Implementation Phase: Standard Operating Procedure

Phase Overview

Prerequisites

Execution Steps

Step 1: Review Task List and Dependencies

Step 2: Execute Tasks Using TDD Workflow

RED Phase: Write Failing Test

GREEN Phase: Make Tests Pass

REFACTOR Phase: Clean Up While Keeping Tests Green

Step 3: Update Task Status

Step 4: Continuous Anti-Duplication Checks

Step 5: Run Tests Continuously

Step 6: Handle Blocked Tasks

Step 7: Integration Testing

Step 8: UI Component Testing (if HAS_UI=true)

Step 9: End-to-End Testing

Step 10: Code Review Checklist

Step 11: Final Validation

Step 12: Commit Implementation

Common Mistakes to Avoid

🚫 Implementation Without Tests (Skipping RED Phase)

🚫 Duplicate Code Written

🚫 Tests Written After Code

🚫 Large Commits Without Context

🚫 Skipping Tests Before Committing

🚫 Ignoring Blocked Tasks

Best Practices

✅ TDD Workflow Example

✅ Anti-Duplication Search Pattern

✅ Continuous Testing Cadence

✅ Commit Message Template

Phase Checklist

Quality Standards

Completion Criteria

Troubleshooting