Workflow Patterns

workflow-patterns — detailed patterns and worked examples

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="[email protected]")
    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 conductor/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

Mobile Compatibility

If applicable:

• Responsive design verified

• Touch interactions work

• Performance acceptable

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

Verification Checkpoints

Why Checkpoints Matter

Checkpoints create restore points for semantic reversion:

• Revert to end of any phase

• Maintain logical code state

• Enable safe experimentation

When to Create Checkpoints

Create checkpoint after:

• All phase tasks complete

• All phase verifications pass

• User approval received

Checkpoint Commit Content

Include in checkpoint commit:

• All uncommitted changes

• Updated plan.md

• Updated metadata.json

• Any documentation updates

How to Use Checkpoints

For reverting:

# Revert to end of Phase 1
git revert --no-commit <phase-2-commits>...
git commit -m "revert: rollback to phase 1 checkpoint"

For review:

# See what changed in Phase 2
git diff <phase-1-sha>..<phase-2-sha>

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

TDD Variations by Task Type

Data Model Tasks

RED: Write test for model creation and validation
GREEN: Implement model class with fields
REFACTOR: Add computed properties, improve types

API Endpoint Tasks

RED: Write test for request/response contract
GREEN: Implement endpoint handler
REFACTOR: Extract validation, improve error handling

Integration Tasks

RED: Write test for component interaction
GREEN: Wire components together
REFACTOR: Improve error propagation, add logging

Refactoring Tasks

RED: Add characterization tests for current behavior
GREEN: Apply refactoring (tests should stay green)
REFACTOR: Clean up any introduced complexity

Working with Existing Tests

When modifying code with existing tests:

Extend, Don't Replace

• Keep existing tests passing

• Add new tests for new behavior

• Update tests only when requirements change

Test Migration

When refactoring changes test structure:

1. Run existing tests (should pass)

2. Add new tests for refactored code

3. Migrate test cases to new structure

4. Remove old tests only after new tests pass

Regression Prevention

After any change:

1. Run full test suite

2. Check for unexpected failures

3. Investigate any new failures

4. Fix regressions before proceeding

Checkpoint Verification Details

Automated Verification

Run before requesting approval:

# Test suite
pytest -v --tb=short

# Coverage
pytest --cov=src --cov-report=term-missing

# Linting
ruff check src/ tests/

# Type checking (if applicable)
mypy src/

Manual Verification Guidance

For manual items, provide specific instructions:

## Manual Verification Steps

### User Registration

1. Navigate to /register
2. Enter valid email: [email protected]
3. Enter password meeting requirements
4. Click Submit
5. Verify success message appears
6. Verify user appears in database

### Error Handling

1. Enter invalid email: "notanemail"
2. Verify error message shows
3. Verify form retains other entered data

Performance Considerations

Test Suite Performance

Keep test suite fast:

• Use fixtures to avoid redundant setup

• Mock slow external calls

• Run subset during development, full suite at checkpoints

Commit Performance

Keep commits atomic:

• One logical change per commit

• Complete thought, not work-in-progress

• Tests should pass after every commit