Code Foundations

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

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:

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

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

Quick Reference: All Skills

CC Skills (Process & Metrics)

APOSD Skills (Design Philosophy)

Shared Reference

• aposd-foundations.md - Complexity vocabulary