shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

code-foundations

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.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

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:

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