workflow-patterns

Guide for implementing tasks using TDD workflow, managing phase checkpoints, handling git commits, and executing the verification protocol that ensures quality throughout implementation.

When to Use This Skill

• Implementing tasks from a track's plan.md
• Following TDD red-green-refactor cycle
• Completing phase checkpoints
• Managing git commits and notes
• Understanding quality assurance gates
• Handling verification protocols
• Recording progress in plan files

TDD Task Lifecycle

Follow these 11 steps for each task:

Step 1: Select Next Task

Read plan.md and identify the next pending [ ] task. Select tasks in order within the current phase. Do not skip ahead to later phases.

Step 2: Mark as In Progress

Update plan.md to mark the task as [~]:

- [~] **Task 2.1**: Implement user validation

Commit this status change separately from implementation.

Step 3: RED - Write Failing Tests

Write tests that define the expected behavior before writing implementation:

• Create test file if needed
• Write test cases covering happy path
• Write test cases covering edge cases
• Write test cases covering error conditions
• Run tests - they should FAIL

Example:

def test_validate_user_email_valid():
    user = User(email="test@example.com")
    assert user.validate_email() is True

def test_validate_user_email_invalid():
    user = User(email="invalid")
    assert user.validate_email() is False

Step 4: GREEN - Implement Minimum Code

Write the minimum code necessary to make tests pass:

• Focus on making tests green, not perfection
• Avoid premature optimization
• Keep implementation simple
• Run tests - they should PASS

Step 5: REFACTOR - Improve Clarity

With green tests, improve the code:

• Extract common patterns
• Improve naming
• Remove duplication
• Simplify logic
• Run tests after each change - they should remain GREEN

Step 6: Verify Coverage

Check test coverage meets the 80% target:

pytest --cov=module --cov-report=term-missing

If coverage is below 80%:

• Identify uncovered lines
• Add tests for missing paths
• Re-run coverage check

Step 7: Document Deviations

If implementation deviated from plan or introduced new dependencies:

• Update tech-stack.md with new dependencies
• Note deviations in plan.md task comments
• Update spec.md if requirements changed

Step 8: Commit Implementation

Create a focused commit for the task:

git add -A
git commit -m "feat(user): implement email validation

- Add validate_email method to User class
- Handle empty and malformed emails
- Add comprehensive test coverage

Task: 2.1
Track: user-auth_20250115"

Commit message format:

• Type: feat, fix, refactor, test, docs, chore
• Scope: affected module or component
• Summary: imperative, present tense
• Body: bullet points of changes
• Footer: task and track references

Step 9: Attach Git Notes

Add rich task summary as git note:

git notes add -m "Task 2.1: Implement user validation

Summary:
- Added email validation using regex pattern
- Handles edge cases: empty, no @, no domain
- Coverage: 94% on validation module

Files changed:
- src/models/user.py (modified)
- tests/test_user.py (modified)

Decisions:
- Used simple regex over email-validator library
- Reason: No external dependency for basic validation"

Step 10: Update Plan with SHA

Update plan.md to mark task complete with commit SHA:

- [x] **Task 2.1**: Implement user validation `abc1234`

Step 11: Commit Plan Update

Commit the plan status update:

git add .claude/context/tracks/*/plan.md
git commit -m "docs: update plan - task 2.1 complete

Track: user-auth_20250115"

Phase Completion Protocol

When all tasks in a phase are complete, execute the verification protocol:

Identify Changed Files

List all files modified since the last checkpoint:

git diff --name-only <last-checkpoint-sha>..HEAD

Ensure Test Coverage

For each modified file:

1. Identify corresponding test file
2. Verify tests exist for new/changed code
3. Run coverage for modified modules
4. Add tests if coverage < 80%

Run Full Test Suite

Execute complete test suite:

pytest -v --tb=short

All tests must pass before proceeding.

Generate Manual Verification Steps

Create checklist of manual verifications:

## Phase 1 Verification Checklist

- [ ] User can register with valid email
- [ ] Invalid email shows appropriate error
- [ ] Database stores user correctly
- [ ] API returns expected response codes

WAIT for User Approval

Present verification checklist to user:

Phase 1 complete. Please verify:
1. [ ] Test suite passes (automated)
2. [ ] Coverage meets target (automated)
3. [ ] Manual verification items (requires human)

Respond with 'approved' to continue, or note issues.

Do NOT proceed without explicit approval.

Create Checkpoint Commit

After approval, create checkpoint commit:

git add -A
git commit -m "checkpoint: phase 1 complete - user-auth_20250115

Verified:
- All tests passing
- Coverage: 87%
- Manual verification approved

Phase 1 tasks:
- [x] Task 1.1: Setup database schema
- [x] Task 1.2: Implement user model
- [x] Task 1.3: Add validation logic"

Record Checkpoint SHA

Update plan.md checkpoints table:

## Checkpoints

| Phase   | Checkpoint SHA | Date       | Status   |
| ------- | -------------- | ---------- | -------- |
| Phase 1 | def5678        | 2025-01-15 | verified |
| Phase 2 |                |            | pending  |

Quality Assurance Gates

Before marking any task complete, verify these gates:

Passing Tests

• All existing tests pass
• New tests pass
• No test regressions

Coverage >= 80%

• New code has 80%+ coverage
• Overall project coverage maintained
• Critical paths fully covered

Style Compliance

• Code follows style guides
• Linting passes
• Formatting correct

Documentation

• Public APIs documented
• Complex logic explained
• README updated if needed

Type Safety

• Type hints present (if applicable)
• Type checker passes
• No type: ignore without reason

No Linting Errors

• Zero linter errors
• Warnings addressed or justified
• Static analysis clean

Security Audit

• No secrets in code
• Input validation present
• Authentication/authorization correct
• Dependencies vulnerability-free

Git Integration

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Types:

• feat: New feature
• fix: Bug fix
• refactor: Code change without feature/fix
• test: Adding tests
• docs: Documentation
• chore: Maintenance

Git Notes for Rich Summaries

Attach detailed notes to commits:

git notes add -m "<detailed summary>"

View notes:

git log --show-notes

Benefits:

• Preserves context without cluttering commit message
• Enables semantic queries across commits
• Supports track-based operations

SHA Recording in plan.md

Always record the commit SHA when completing tasks:

- [x] **Task 1.1**: Setup schema `abc1234`
- [x] **Task 1.2**: Add model `def5678`

This enables:

• Traceability from plan to code
• Semantic revert operations
• Progress auditing

Handling Deviations

During implementation, deviations from the plan may occur. Handle them systematically:

Types of Deviations

Scope Addition Discovered requirement not in original spec.

• Document in spec.md as new requirement
• Add tasks to plan.md
• Note addition in task comments

Scope Reduction Feature deemed unnecessary during implementation.

• Mark tasks as [-] (skipped) with reason
• Update spec.md scope section
• Document decision rationale

Technical Deviation Different implementation approach than planned.

• Note deviation in task completion comment
• Update tech-stack.md if dependencies changed
• Document why original approach was unsuitable

Requirement Change Understanding of requirement changes during work.

• Update spec.md with corrected requirement
• Adjust plan.md tasks if needed
• Re-verify acceptance criteria

Deviation Documentation Format

When completing a task with deviation:

- [x] **Task 2.1**: Implement validation `abc1234`
  - DEVIATION: Used library instead of custom code
  - Reason: Better edge case handling
  - Impact: Added email-validator to dependencies

Error Recovery

Failed Tests After GREEN

If tests fail after reaching GREEN:

1. Do NOT proceed to REFACTOR
2. Identify which test started failing
3. Check if refactoring broke something
4. Revert to last known GREEN state
5. Re-approach the implementation

Checkpoint Rejection

If user rejects a checkpoint:

1. Note rejection reason in plan.md
2. Create tasks to address issues
3. Complete remediation tasks
4. Request checkpoint approval again

Blocked by Dependency

If task cannot proceed:

1. Mark task as [!] with blocker description
2. Check if other tasks can proceed
3. Document expected resolution timeline
4. Consider creating dependency resolution track

Best Practices

1. Never skip RED: Always write failing tests first
2. Small commits: One logical change per commit
3. Immediate updates: Update plan.md right after task completion
4. Wait for approval: Never skip checkpoint verification
5. Rich git notes: Include context that helps future understanding
6. Coverage discipline: Don't accept coverage below target
7. Quality gates: Check all gates before marking complete
8. Sequential phases: Complete phases in order
9. Document deviations: Note any changes from original plan
10. Clean state: Each commit should leave code in working state
11. Fast feedback: Run relevant tests frequently during development
12. Clear blockers: Address blockers promptly, don't work around them

Memory Protocol (MANDATORY)

Before starting:

cat .claude/context/memory/learnings.md

After completing:

• New pattern -> .claude/context/memory/learnings.md
• Issue found -> .claude/context/memory/issues.md
• Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.