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:

Identify corresponding test file
Verify tests exist for new/changed code
Run coverage for modified modules
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:

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

Checkpoint Rejection

If user rejects a checkpoint:

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

Blocked by Dependency

If task cannot proceed:

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

Best Practices

Never skip RED: Always write failing tests first
Small commits: One logical change per commit
Immediate updates: Update plan.md right after task completion
Wait for approval: Never skip checkpoint verification
Rich git notes: Include context that helps future understanding
Coverage discipline: Don't accept coverage below target
Quality gates: Check all gates before marking complete
Sequential phases: Complete phases in order
Document deviations: Note any changes from original plan
Clean state: Each commit should leave code in working state
Fast feedback: Run relevant tests frequently during development
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.

workflow-patterns