code-foundations

name

code-foundations

description

Classify code tasks and execute task-specific checklists with quality gates. Route to WRITE, DEBUG, REVIEW, OPTIMIZE, REFACTOR, SIMPLIFY, or SECURE workflows, each invoking relevant CC and APOSD skills. Produce classification statement plus DONE/NOT DONE verdict with mandatory pre-commit verification. Use when writing, debugging, reviewing, fixing, implementing, optimizing, refactoring, simplifying, or securing code. Triggers on: implement, build, create, debug, fix bug, broken, error, review, audit, optimize, slow, performance, refactor, clean up, simplify, confusing, too complex, secure, vulnerability.

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:

1. Classify the task (5 seconds)
2. State what you're skipping and why
3. Fix ONLY—no refactoring, no cleanup
4. Verify fix works
5. 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