Development Cycle: Self-Review + Peer Review

Run this after completing a unit of work. Guides you through self-review, quality gates, and peer review before committing.

Resource Hint: sonnet - iterative code review and quality gate checks

Tool-agnostic: This command works with any development tool or peer review process. Claude Code users invoke as /pb-cycle. Using another tool? Read this file as Markdown and follow the checklist with your tool. See /docs/using-with-other-tools.md for adaptation examples.

When to Use This Command

• After completing a feature/fix - Before committing changes
• During development iterations - Each cycle of code → review → refine
• Before creating a PR - Final self-review pass
• When unsure if code is ready - Checklist helps verify completeness

Step 0: Outcome Verification (Critical)

Before self-review, verify you’ve achieved the defined outcomes.

Pull up the outcome clarification document (created during /pb-start):

cat todos/work/[task-date]-outcome.md

Verify each success criterion:

• Success criterion 1: VERIFIED? (How? Measured? Tested?)
• Success criterion 2: VERIFIED?
• Success criterion 3: VERIFIED?

If outcomes are NOT met:

• Stop. Don’t proceed to self-review.
• Ask: “What’s missing?” “Why wasn’t this done?”
• Either complete the work, or escalate if blocked.

If outcomes ARE met:

• Proceed to Step 1 (Self-Review)

Why this matters: Outcome verification prevents the common trap of “code is done but doesn’t solve the problem.” Verify the problem is solved before polishing the code.

Step 1: Self-Review

Review your own changes critically before requesting peer review.

Use the Self-Review Checklist from /docs/checklists.md:

• Code Quality: hardcoded values, dead code, naming, DRY, error messages
• Security: no secrets, input validation, parameterized queries, auth checks, logging
• Testing: unit tests, edge cases, error paths, all tests passing
• Documentation: comments for “why”, clear names, API docs updated
• Database: reversible migrations, indexes, constraints, no breaking changes
• Performance: N+1 queries, pagination, timeouts, unbounded loops

Step 2: Quality Gates

Run before proceeding to peer review:

make lint        # Linting passes
make typecheck   # Type checking passes
make test        # All tests pass

All gates must pass. Fix issues before proceeding.

Step 3: Peer Review

Request review from senior engineer perspective.

For reviewers: Use /pb-review-code for the complete code review checklist.

CRITICAL: Reviewers must verify outcomes before approving.

Before approving, reviewer should check:

• Outcomes were defined (in outcome clarification document)
• Success criteria are met (verified in code/tests)
• If outcomes not met: Ask author to complete work or explain why criteria changed
• If outcomes met: Proceed to code review

Why this matters: A perfectly written feature that doesn’t solve the problem is waste. Verify the problem is solved before approving.

Important: Peer review assumes /pb-preamble thinking (challenge assumptions, surface flaws, question trade-offs) and applies /pb-design-rules (check for clarity, simplicity, modularity).

Reviewer should:

• Challenge architectural choices and design decisions
• Check that code follows design rules: Clarity, Simplicity, Modularity
• Ask clarifying questions about trade-offs
• Surface flaws directly
• Verify outcomes and success criteria met (not just code quality)

Author should welcome and respond to critical feedback. This is how we catch problems early-in code review, not production.

Architecture Review

• Changes align with existing patterns
• No unnecessary complexity introduced
• Separation of concerns maintained
• Dependencies appropriate (not pulling in large libs for small tasks)

Correctness Review

• Logic handles all stated requirements
• Edge cases considered
• Error handling is comprehensive
• Race conditions considered for concurrent operations

Maintainability Review

• Code is readable without extensive comments
• Functions are single-purpose and reasonably sized
• Magic values extracted to constants
• Naming clearly expresses intent

Security Review

• No injection vulnerabilities (SQL, command, etc.)
• Authorization properly enforced
• Sensitive operations properly audited
• No information leakage in error responses

Test Review

• Tests actually verify the behavior (not just coverage%)
• Test names describe what they verify
• Mocks/stubs used appropriately
• No flaky tests introduced

Step 4: Address Feedback

If issues identified:

1. Fix the issues - Don’t argue, just fix
2. Re-run self-review - Ensure fix didn’t break something else
3. Re-run quality gates - All must pass again
4. Request re-review if needed - For significant changes

Step 5: Commit

After reviews pass, create a logical commit:

git add [specific files]    # NEVER use git add . or git add -A
git status                  # Verify what's staged
git diff --staged           # Review staged changes
git commit -m "$(cat <<'EOF'
type(scope): subject

Body explaining what and why
EOF
)"

Warning: Never use git add . or git add -A. Always stage specific files intentionally. Blind adds lead to:

• Committing debug code, secrets, or unrelated changes
• Losing track of what’s in each commit
• Breaking atomic commit discipline

Commit Message Guidelines

Types:

• feat: New feature
• fix: Bug fix
• refactor: Code change (no behavior change)
• docs: Documentation only
• test: Adding/updating tests
• chore: Build, config, tooling
• perf: Performance improvement

Good Example:

feat(audio): add section track for study mode

- SectionTrack component with labeled horizontal pipeline
- Progress calculation spans all sections
- Visual states: completed (filled), current (glow), upcoming (hollow)

Bad Example:

update code

Step 6: Update Tracker

After each commit, update your progress tracker to capture what’s done and what remains.

# Check for master tracker / phase docs
ls todos/*.md
ls todos/releases/*/

Update in tracker:

• Mark completed task as done
• Note commit hash for reference
• Review remaining tasks
• Identify next task for upcoming iteration

Why this matters: Trackers keep you aligned with original goals. Without updates:

• You lose track of progress
• Next steps become “guessed” instead of planned
• Scope creep goes unnoticed
• Context is lost between sessions

Tracker update template:

## [Date] Iteration Update

**Completed:**
- [x] Task description - commit: abc1234

**In Progress:**
- [ ] Next task - starting next iteration

**Remaining:**
- [ ] Task 3
- [ ] Task 4

Tip: If no tracker exists, create one. Even a simple todos/tracker.md prevents drift.

Step 7: Context Checkpoint

After committing, assess context health. See /pb-claude-orchestration for detailed context management strategies (compaction timing, thresholds, preservation techniques).

Quick check: If 3+ iterations completed or 5+ files read this session, consider checkpointing - update tracker, start fresh session.

Quick Cycle Summary

1. Write code following standards
2. Self-review using checklist above
3. Run: make lint && make typecheck && make test
4. Request peer review (senior engineer perspective)
5. Address any feedback
6. Commit with clear message (specific files, not git add -A)
7. Update tracker (mark done, note commit, identify next)
8. Context checkpoint (assess if session should continue or refresh)
9. Repeat for next unit of work

When to Stop and Ask

• Requirements are unclear
• Multiple valid approaches exist
• Change impacts system architecture
• Peer review raises design concerns
• Scope is expanding beyond original intent

Don’t proceed with uncertainty. Clarify first.

Anti-Patterns to Avoid

Iteration Frequency

Commit after each meaningful unit of work:

Don’t wait until end of session. Commit incrementally.

Integration with Playbook

Part of feature development workflow:

• /pb-start → Create branch, set iteration rhythm
• /pb-resume → Get back in context (if context switching)
• /pb-cycle → Self-review + peer review (YOU ARE HERE)
  • Includes: /pb-testing (write tests), /pb-standards (check principles), /pb-security (security gate)
  • Peer reviewer uses: /pb-review-code (code review checklist)
• /pb-commit → Craft atomic commits (after approval)
• /pb-pr → Create pull request
• /pb-review-* → Additional reviews if needed
• /pb-release → Deploy

Key integrations during /pb-cycle:

• Peer Review: /pb-review-code for reviewer’s code review checklist
• Testing: /pb-testing for test patterns (unit, integration, E2E)
• Security: /pb-security checklist during self-review
• Logging: /pb-logging standards for logging validation
• Standards: /pb-standards for working principles
• Documentation: /pb-documentation for updating docs alongside code

After /pb-cycle approval:

• /pb-commit - Craft atomic, well-formatted commit
• /pb-pr - Create pull request with context

See also: /docs/integration-guide.md for how all commands work together

Related Commands

• /pb-start - Begin new development work
• /pb-commit - Create atomic commits after cycle
• /pb-pr - Create pull request when ready
• /pb-review-code - Code review checklist for peer reviewers
• /pb-testing - Test patterns and strategies

Every iteration gets the full cycle. No shortcuts.