Feature Development
Clarify → Design → Tests → Implement → Review → Commit
Bug Fixing
Reproduce → Regression test → Diagnose → Fix → Validate
COLBLOCK
Legacy Refactoring
Map → Slice → Freeze tests → Plan → Step-by-step → Clean up
Code Review
AI pre-review → Human review
(AI augments, never replaces)
Clarify requirements
Write a short problem statement.
Capture constraints (stack, security, compliance).
Design first (with AI)
Ask for architecture options.
Decide on endpoints, data models, responsibilities — before code.
Define tests
Ask AI to propose test cases.
Write them in your repo.
COLBLOCK
Generate implementation
Use AI to scaffold code.
Keep changes small, focused, reviewable.
Review and harden
Run tests, linters, security checks.
Manually review all AI-generated code.
Commit and document
Small commits. Clear messages.
Update README, ADRs, or rules files if behavior changed.
Treat the assistant as a pair programmer — it handles options and boilerplate; you own design and final decisions.
Context: @src @tests @docs
Task: Add a feature so that users can mark a todo as completed.
Requirements:
- Keep the existing API style.
- Preserve current data model where possible.
- Ensure the operation is idempotent.
Please:
1. Propose a small design change (DB, API, service layer).
2. List 3–5 test cases we should cover.
3. Stop after the design and test list — do not write code yet.
Reproduce
Capture logs, stack trace, exact “steps to reproduce.”
Create a regression test
Write a test that currently fails with the bug.
Let AI suggest causes
Provide the error and relevant files.
Ask “what could cause this?”
COLBLOCK
Let AI propose a fix
Ask for one focused change, not a rewrite.
Run tests & review
All tests (old + new) must pass.
Manually review the fix and surrounding code.
Document
Include the bug ID in the commit message.
AI is useful for hypothesis generation and navigating unfamiliar code — but the final fix must be validated with tests and reasoning.
Bug: When creating a user with an existing email, the API crashes with
"AttributeError: 'NoneType' object has no attribute 'id'".
Context:
- Error log: [paste stack trace]
- Relevant files: @src/user_service.py @src/user_repository.py
Tasks:
1. Identify the most likely root cause.
2. Propose a regression test that reproduces this bug.
3. Suggest a minimal fix that keeps existing behavior.
Stop after showing the test and the diff for the fix.
Map the area
Find where the concept lives.
Write a short description of current behavior.
Define a narrow slice
“Refactor validation logic in UserService only”
— not “rewrite UserService.”
Freeze behavior with tests
Add tests around the slice you’re about to touch.
COLBLOCK
Let AI propose a plan
Ask for a short, numbered refactoring plan.
Apply changes step by step
After each step: run tests, review diffs, commit.
Clean up
Remove dead code, update docs.
"Explain how validation currently works.
Propose a small refactor in at most 4 steps.
Wait for my confirmation before editing files."
AI pre-review — scan for obvious issues:
Human review — focus on:
COLBLOCK
AI review prompt:
Review this diff for:
1. Logic correctness and edge cases
2. Security issues (auth, validation, injections)
3. Performance pitfalls (N+1 queries)
4. Consistency with existing architecture
5. Testing gaps
Suggest concrete, minimal improvements.
AI review augments — it never replaces a human reviewer.