Code Foundations

When in doubt, load this skill. When NOT in doubt, load it anyway.

Master Checklist: Execute In Order

Phase 1: Classification (MANDATORY - Do First)

[ ] 1.1 Identify task type from user signals: | Signal | Task Type | |--------|-----------| | "implement", "write", "build", "add", "create" | → WRITE | | "debug", "fix bug", "failing", "broken", "error" | → DEBUG | | "review", "check", "audit", "is this good?" | → REVIEW | | "optimize", "slow", "performance", "faster" | → OPTIMIZE | | "refactor", "clean up", "improve structure" | → REFACTOR | | "simplify", "too complex", "confusing" | → SIMPLIFY | | "secure", "vulnerability", "validate input" | → SECURE |
[ ] 1.2 State classification: "This is a [TASK TYPE] task"
[ ] 1.3 If ambiguous, ask: "Are you looking for [option A], [option B], or something else?"

Phase 2: Mindset Check (For WRITE, DEBUG, REFACTOR)

[ ] 2.1 INVOKE cc-developer-character
[ ] 2.2 Verify: Am I thinking strategically, not tactically?
[ ] 2.3 Check for rationalization red flags (see below)

Phase 2.5: Pattern Reuse Gate (For WRITE, DEBUG, REFACTOR, SECURE)

MANDATORY: Before implementing, search the codebase.

[ ] 2.5.1 Search: How is this done elsewhere in this codebase?
[ ] 2.5.2 Identify: What patterns exist for this type of work?
[ ] 2.5.3 Decide: Follow existing pattern OR document why diverging

| If | Then | |----|------| | Pattern exists and is good | Follow it exactly | | Pattern exists but mediocre | Follow anyway (consistency > perfection) | | Pattern exists but bad | Document why diverging, consider fixing globally | | No pattern exists | You're establishing one - be deliberate |

See: pattern-reuse-gate.md

Phase 3: Execute Task-Specific Checklist

Go to the checklist for your task type:

WRITE → Write Checklist
DEBUG → Debug Checklist
REVIEW → Review Checklist
OPTIMIZE → Optimize Checklist
REFACTOR → Refactor Checklist
SIMPLIFY → Simplify Checklist
SECURE → Secure Checklist

Phase 4: Pre-Commit Gate (MANDATORY - Before "Done")

[ ] 4.1 INVOKE aposd-verifying-correctness
[ ] 4.2 Requirements: Each requirement mapped to code?
[ ] 4.3 Concurrency: Shared state protected?
[ ] 4.4 Errors: All failure points handled?
[ ] 4.5 Resources: All acquired resources released?
[ ] 4.6 Boundaries: Edge cases (empty, null, huge) handled?
[ ] 4.7 Security: Untrusted input validated?
[ ] 4.8 State verdict: DONE or NOT DONE (list blockers)

WRITE Checklist

Goal: Create new code with good design

Prerequisites

[ ] INVOKE cc-developer-character (mindset)
[ ] INVOKE cc-construction-prerequisites (architecture ready?)

Design Phase

[ ] INVOKE aposd-designing-deep-modules
[ ] Sketch 2-3 radically different approaches (not just "think through")
[ ] Compare approaches: Which has simplest interface?
[ ] Choose approach and document rationale
[ ] Verify depth: Interface much simpler than implementation?

Implementation Phase

[ ] INVOKE aposd-improving-code-clarity
[ ] Write interface comments BEFORE implementation
[ ] INVOKE cc-pseudocode-programming
[ ] Write pseudocode, then translate to real code
[ ] Names precise? (Can someone guess meaning in isolation?)
[ ] Names consistent? (Same name = same thing everywhere?)

Verification Phase (Parallel Subagents)

[ ] CHECKER(cc-routine-and-class-design)
[ ] CHECKER(cc-defensive-programming)

See references/checker-dispatch.md

Pre-Commit

[ ] Run Phase 4 checklist

DEBUG Checklist

Goal: Find and fix bug without making design worse

Investigation Phase

[ ] INVOKE cc-developer-character (mindset)
[ ] INVOKE cc-quality-practices (Scientific Method)
[ ] Stabilize error: Can you reproduce reliably?
[ ] Locate error: Use binary search / divide-and-conquer
[ ] Understand root cause (not just symptoms)

Fix Phase

[ ] INVOKE aposd-maintaining-design-quality
[ ] Ask: "Is current design still optimal given this fix?"
[ ] If NO: Refactor first, then fix
[ ] If YES: Make fix within existing design
[ ] INVOKE cc-refactoring-guidance
[ ] Fix ONLY the bug (don't mix fix + refactor in one commit)
[ ] Commit fix separately from any cleanup

Verification Phase

[ ] Verify fix actually works
[ ] Check for similar bugs elsewhere (same pattern?)
[ ] INVOKE cc-quality-practices: Search for similar defects

Pre-Commit

[ ] Run Phase 4 checklist

REVIEW Checklist

Goal: Detect design problems and complexity

CHECKER pattern: See references/checker-dispatch.md

Quick Checks (Inline)

Complexity Symptoms:

[ ] Change amplification? (Simple change = many modifications?)
[ ] Cognitive load? (Must know too much to work here?)
[ ] Unknown unknowns? (Unclear what code/info is needed?) ← Worst

Module Depth:

[ ] Interface simpler than implementation?
[ ] Few methods (not many small ones)?
[ ] Information hidden (not leaked across modules)?

Red Flags:

[ ] Shallow module (interface ≈ implementation)
[ ] Information leakage (same knowledge in multiple places)
[ ] Pass-through methods (just delegates to another)

Full Checklists (Parallel Subagents)

[ ] CHECKER(aposd-reviewing-module-design)
[ ] CHECKER(cc-routine-and-class-design)
[ ] CHECKER(cc-quality-practices)

Output

[ ] List Findings (from all agents)
[ ] List Questions (need more context)
[ ] Note Positive patterns

OPTIMIZE Checklist

Goal: Improve performance based on measurement, not intuition

Measurement Gate (MANDATORY)

[ ] INVOKE cc-performance-tuning
[ ] INVOKE aposd-optimizing-critical-paths
[ ] STOP: Have you measured? (No measurement = no optimization)
[ ] Profile data collected? (timing, call counts, memory)
[ ] Specific hotspot identified? (not just "it's slow")
[ ] Baseline established?
[ ] Which dimension? (throughput / latency / memory / CPU)

Fundamental Fixes (Try First)

[ ] Can you add a cache?
[ ] Can you use a better algorithm?
[ ] Can you bypass layers?
[ ] If YES to any → implement and re-measure

Critical Path Redesign (Last Resort)

[ ] What's minimum code for common case?
[ ] Disregard existing structure—what's ideal?
[ ] Define "the ideal" even if not fully achievable

Verification

[ ] Re-measure with same methodology
[ ] Faster with data? → Keep
[ ] Simpler AND at least as fast? → Keep
[ ] Neither? → BACK OUT changes

Pre-Commit

[ ] Run Phase 4 checklist

REFACTOR Checklist

Goal: Improve structure without changing behavior

Prerequisites

[ ] INVOKE cc-developer-character (mindset)
[ ] Code currently WORKS? (All tests pass?)
[ ] If NO → This is FIXING, not refactoring. Go to DEBUG checklist.

Planning

[ ] INVOKE cc-refactoring-guidance
[ ] INVOKE aposd-maintaining-design-quality
[ ] Design fundamentally sound? (If NO → consider rewrite)
[ ] Changes touch >30% of module? (If YES → consider rewrite)
[ ] Make list of specific refactoring steps

Execution (One At A Time)

[ ] Save starting code (version control checkpoint)
[ ] Do ONE refactoring
[ ] Recompile and retest
[ ] State: "Tests pass after [change]"
[ ] Commit if tests pass
[ ] Repeat for next refactoring

Verification (Parallel Subagents)

[ ] CHECKER(cc-control-flow-quality)
[ ] CHECKER(cc-routine-and-class-design)

See references/checker-dispatch.md

Quick Checks:

[ ] Behavior preserved? (Same tests pass)
[ ] Design improved? (Simpler interfaces, less duplication)

Pre-Commit

[ ] Run Phase 4 checklist

SIMPLIFY Checklist

Goal: Reduce complexity, not just relocate it

Analysis

[ ] INVOKE aposd-simplifying-complexity
[ ] Identify complexity symptoms present
[ ] Identify what makes it complex (dependencies? obscurity?)

Error Reduction Hierarchy (Apply In Order)

For each error condition:

[ ] Level 1 - Define out: Can semantics eliminate this error?
[ ] Level 2 - Mask: Can low-level code handle without exposing?
[ ] Level 3 - Aggregate: Can multiple errors share one handler?
[ ] Level 4 - Crash: Rare, unrecoverable, app-level only?
[ ] Document which level applied and why

Pull Complexity Down (Check All Three)

[ ] Is complexity related to module's existing functionality?
[ ] Will pulling down simplify code elsewhere?
[ ] Will pulling down simplify module's interface?
[ ] All three YES? → Pull down. Otherwise → Leave.

Verification

[ ] Interfaces simpler than before?
[ ] Callers do less work than before?
[ ] Error handling consolidated or eliminated?
[ ] Complexity REDUCED (not just relocated)?

Pre-Commit

[ ] Run Phase 4 checklist

SECURE Checklist

Goal: Protect against malicious or malformed input

Analysis (Parallel Subagents)

[ ] CHECKER(cc-defensive-programming)
[ ] INVOKE aposd-simplifying-complexity (error reduction context)

See references/checker-dispatch.md

Identify:

[ ] All external input sources
[ ] Trust boundaries

Validation (For Each External Input)

[ ] Input validated before use?
[ ] No string concatenation for SQL/shell/HTML?
[ ] Path traversal prevented?
[ ] Secrets not logged or exposed in errors?
[ ] Auth/authz checked BEFORE action?

Error Handling

[ ] No empty catch blocks?
[ ] Error messages don't leak security info?
[ ] Assertions used for bugs only (not expected errors)?

Pre-Commit

[ ] Run Phase 4 checklist

Rationalization Red Flags

If you think any of these, STOP and apply the checklist anyway:

| Thought | Reality | |---------|---------| | "This is simple/trivial" | Simple tasks have HIGHEST error rates | | "I can already see the issue" | Seeing ≠ systematic verification | | "I already know how to do this" | Knowing ≠ executing checklist | | "It's just config, not code" | Config that affects runtime IS code | | "The code already works" | Your CHANGE can break what worked | | "I'll refactor later" | Later = never | | "Just make it work" | Tactical thinking → permanent slowdown | | "I don't have time" | Checklist takes minutes; debugging takes hours | | "It's just one line" | One-line changes have highest error rate | | "Tests pass, so it's done" | Tests check behavior, not design quality |

Crisis Mode (Production Down)

You STILL must:

[ ] Classify the task (5 seconds)
[ ] State what you're skipping and why
[ ] Fix ONLY—no refactoring, no cleanup
[ ] Verify fix works
[ ] Commit to returning within 24 hours for full checklist

What you may NOT skip:

Input validation on external data
Verifying fix actually works
One sentence explaining WHY the fix works

Two Skill Families

| Family | Source | Focus | Prefix | |--------|--------|-------|--------| | Code Complete | McConnell | Process rigor, metrics, checklists | cc-* | | APOSD | Ousterhout | Design philosophy, complexity reduction | aposd-* |

Use both. CC provides tactical rigor; APOSD provides strategic philosophy.

Quick Reference: All Skills

CC Skills (Process & Metrics)

| Skill | Use For | |-------|---------| | cc-developer-character | Mindset check before WRITE/DEBUG/REFACTOR | | cc-construction-prerequisites | Architecture ready before coding | | cc-pseudocode-programming | Design-before-code | | cc-routine-and-class-design | Cohesion, coupling, inheritance | | cc-defensive-programming | Error handling, validation | | cc-refactoring-guidance | Safe refactoring process | | cc-quality-practices | Testing, debugging, reviews | | cc-control-flow-quality | Nesting, complexity, loops | | cc-data-organization | Variables, types, data structures | | cc-code-layout-and-style | Formatting, visual structure | | cc-performance-tuning | Optimization process | | cc-integration-practices | Build, integration |

APOSD Skills (Design Philosophy)

| Skill | Use For | |-------|---------| | aposd-designing-deep-modules | Interface design, design-it-twice | | aposd-simplifying-complexity | Error reduction, pull-down technique | | aposd-improving-code-clarity | Comments-first, naming | | aposd-maintaining-design-quality | Strategic vs tactical mindset | | aposd-reviewing-module-design | Complexity symptoms detection | | aposd-optimizing-critical-paths | Measure-first optimization | | aposd-verifying-correctness | Pre-commit verification |

Shared Reference

aposd-foundations.md - Complexity vocabulary

code-foundations

Code Foundations

Master Checklist: Execute In Order

Phase 1: Classification (MANDATORY - Do First)

Phase 2: Mindset Check (For WRITE, DEBUG, REFACTOR)

Phase 2.5: Pattern Reuse Gate (For WRITE, DEBUG, REFACTOR, SECURE)

Phase 3: Execute Task-Specific Checklist

Phase 4: Pre-Commit Gate (MANDATORY - Before "Done")

WRITE Checklist

Prerequisites

Design Phase

Implementation Phase

Verification Phase (Parallel Subagents)

Pre-Commit

DEBUG Checklist

Investigation Phase

Fix Phase

Verification Phase

Pre-Commit

REVIEW Checklist

Quick Checks (Inline)

Full Checklists (Parallel Subagents)

Output

OPTIMIZE Checklist

Measurement Gate (MANDATORY)

Fundamental Fixes (Try First)

Critical Path Redesign (Last Resort)

Verification

Pre-Commit

REFACTOR Checklist

Prerequisites

Planning

Execution (One At A Time)

Verification (Parallel Subagents)

Pre-Commit

SIMPLIFY Checklist

Analysis

Error Reduction Hierarchy (Apply In Order)

Pull Complexity Down (Check All Three)

Verification

Pre-Commit

SECURE Checklist

Analysis (Parallel Subagents)

Validation (For Each External Input)

Error Handling

Pre-Commit

Rationalization Red Flags

Crisis Mode (Production Down)

Two Skill Families

Quick Reference: All Skills

CC Skills (Process & Metrics)

APOSD Skills (Design Philosophy)

Shared Reference