damgyeah/foundation

Sketch types, signatures, and module boundaries before writing code, compare at least two candidate shapes, get a rubber-duck critique, then implement against the chosen sketch. Use for 'architect this', 'design this', or any code that crosses a function boundary where jumping to code would lock in the wrong shape.

Vet a perf measurement (limiter, tuning, limits, errors, repeatability, relevance, and whether the work happened) before you report or act on it. Use when you run a benchmark or report a speedup or regression you measured.

Find what a change could break somewhere else before it ships, beyond the diff, and prove the one fact it's safe because of by running real code instead of writing it up. Use for 'blast radius of X', 'what could this break', or reviewing a small diff you don't trust.

Find the mistakes agents keep repeating in this repo and make each one impossible. Try architecture first, then types, then a lint whose error names the fix, then a test, and write docs last. Prove each check fails on a real past mistake. Repeat this each time the person corrects you. Use when the same correction comes up twice, or when asked to make a repeated mistake impossible.

Engineering workflow for nontrivial work in a repository: route the task to a playbook (investigation, bug fix, feature, refactoring, prototype, multi-phase plan, opening a PR, session pickup, pause safely), apply the principles that shape each decision, delegate to subagents, and prove the result before reporting. Use it first for any nontrivial task (a bug, a feature, a refactor, a design or how-and-why question, picking up or pausing work), when asked for foundation mode, or for /foundation:foundation-mode.

Explain how code works: subsystem architecture, runtime flow, where things live, and placement or ownership questions ("where should this live", "is this the right layer"). Use before changing unfamiliar code. Use why for motivation.

Adversarial review of a change from two independent reviewers, an Opus reviewer with the full rubric and the code-review agent, judged into act on, consider, noted, and dismissed. Use for 'interrogate', 'adversarial review', 'challenge this', 'stress test this code', 'find blind spots', or a contested design before it ships.

Before review, strip comments that narrate or excuse code, act on the flagged code, and offer structural encodings for constraint comments. Use for 'remove the comments', 'no comments', or the pre-review pass in foundation playbooks.

Apply when two or more fixes that share one premise have failed the same gate. Write the premise down and test it directly before you write another fix that assumes it.

Apply when wiring validation, error handling, or framework adapters. Concentrate guards at system boundaries (CLI, config, network, external APIs); trust internal types and keep business logic in pure functions.

Apply to any non-trivial work, not just bulk work: edits, migrations, analyses, checks. Build the tool that does it or proves it (codemod, script, generator, or a skill your subagents follow) instead of working by hand. The tool is the artifact a reviewer can rerun.

Apply when you catch yourself writing the same instruction a second time, or notice a recurring correction. Encode the rule as a lint, type, metadata flag, runtime check, or script instead of more text.

Apply when facing a novel UI interaction or architectural decision with no precedent in the codebase. Build 2-3 competing prototypes and compare side by side before committing.

Apply when product, UX, or feature-scope tradeoffs come up. Choose user delight over implementation convenience; ship fewer polished features over more rough ones.

Apply before you trust, report, or act on a number you measured: a speedup, a regression, a throughput, a latency, or an eval result. Find what limits it, and rule out that it measured something other than the work you think.

Apply when debugging. Trace each symptom back to the first place the system went wrong and fix it there. A guard is a fix only when the state it handles is legitimate.

Apply before writing logic: choosing core types and data structures, sequencing scaffold-vs-feature work, asking what concurrent actors share. Get the data structures right so downstream code becomes obvious.

Apply when context is filling up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents; keep summaries in the main thread, not raw payloads.

Apply when refactoring, evaluating diff size, or tempted to add abstractions, layers, or signal threading. Bias toward deletion and the smallest change that solves the problem.

Apply when designing commands, lifecycle steps, or processing loops that run amid crashes, restarts, and retries. Converge to the same end state regardless of partial prior runs.

Apply when introducing a new internal API while old callers still exist. Migrate callers and delete the old API in the same wave instead of preserving compatibility layers.

Apply when reviewing or shaping code that's hard to trace. Count layers between question and answer, and hidden state in the reader's head; collapse one-caller wrappers and shrink mutable scope.

Apply when writing stateful logic, or when code branches a lot or repeats a shape assumption across files.

Apply when tempted to ask 'should I do X?' on reversible work.

Apply during planned rewrites and migrations with explicit phase boundaries. Converge on the target architecture; don't preserve smooth intermediate states with throwaway compatibility code.

Apply after completing a task, before declaring done. Verify against the real artifact (run the feature, read the actual value, inspect the diff), not a proxy, self-report, or 'it compiles.'

Apply when integrating a new requirement into an existing design.

Apply when concurrent actors might write to the same file, branch, key, or state object. Eliminate the sharing first; serialize structurally only when one shared writer is a real invariant.

Apply to multi-step work (sweeps, migrations, runs of similar edits) and to how you stack commits and PRs. Break work into small units that each end in a verifiable state, check each before the next, and order delivery so the sequence proves itself to a reviewer.

Apply when sequencing an addition, refactor, or rewrite. Remove dead code, redundant validators, and stub references first, then build on the simpler base.

Apply when you write, change, or keep a test. Assert what the code's users can observe, so that the test fails when that behavior breaks and keeps passing when only the internals change.

Apply when designing types, reviewing a function signature, or writing code in any statically-typed language. Make illegal states unrepresentable, brand semantic primitives, parse external data at boundaries, exhaust variants, derive from authoritative schemas.

Mine the current session for durable learnings with three parallel reviewers, then route each to a concrete edit on a skill the session used. Use when the person says reflect or asks what this session should teach future agents.

Keep a reviewable decision trail for long-running or unattended work: a TSV log with one row per decision (what, why, evidence, result). Local by default; commit it when a reviewer needs the trail to trust the result. Use for a decision log, autonomous or multi-phase runs, or work a human reviews after stepping away.

Use only when the user explicitly asks for TDD, a failing test, or a regression test, OR when the bug has an obvious cheap local test target. Skip when the test path is unclear, expensive, integration-heavy, or not requested.

Layered technical-writing standard: Diátaxis structure, Google developer style sentences, STE instruction rules, Global English syntax. Use when writing or reviewing docs, RFCs, readmes, PR descriptions, or commit messages.

Cut AI tells from any writing.

Explain why code is shaped the way it is: design rationale, tradeoffs, regressions, data-backed thresholds. Searches git history, GitHub pull requests and issues, and any other evidence source available in the session in parallel, then returns a cited, confidence-tiered answer. Use how for runtime behavior.