Tw Codebase Doctrine

Codebase Doctrine

Mission

Determine what future maintainers and coding agents must know, decide, reject, and prove to change a repository safely.

authorized intent
-> named search questions
-> artifact-bound evidence
-> closed claim graph
-> current/target authorities, laws, invariants, boundaries, failures, proof
-> strongest knowledge destinations
-> zero or one root skill plus zero to five focused skill candidates

The doctrine is a canonical synthesis for one pinned repository and intent state. It is never stronger than current code, executable proof, or explicit user authority.

Activation boundary

Use only when the request contains both deep repository understanding and durable correctness doctrine, knowledge routing, authority/proof maps, or repo-specific skill recommendations.

Do not use for: quick onboarding or architecture fingerprinting (use tw-codebase-archaeology); one feature, bug trace, or isolated invariant (use tw-invariant-ace); ordinary implementation or generic review; skill brainstorming without repository evidence; or direct skill creation. This skill is read-only — persistence and skill creation require separate explicit authorization.

Modes

Pick exactly one. Do not force a full doctrine into survey, portfolio, audit, or delta work.

Phase 0 — intent before doctrine

Before asking intent questions, inspect enough to distinguish discoverable facts from user-owned choices: repository guidance and existing skills; manifests and build/test/release roots; major subsystems and cross-cutting flows; deployment/distribution shape; visible correctness, compatibility, security, performance, and operational priorities.

Then clarify only material user-owned choices (ask directly, or hand to a clarifying-questions pass): target boundary, consumers, current-state vs target-state posture, desired products, correctness priorities, non-goals, proof bar, compatibility/migration posture, persistence. Do not ask for repository facts, laws, implementation design, or skill-file content — discover those.

Record an intent capsule: target, consumers, posture, products, priorities, non-goals, proof bar, a primary correctness question, a primary risk, explicitly-sourced user invariant hypotheses (if any), and assumptions/deferrals. The capsule does not declare repository-derived laws before research.

Artifact state

Pin and bind all evidence to one state: repository_root, repository_name, branch, head, dirty_state, scope, intent_id, captured_at. Re-pin before closure; reject stale evidence after a relevant head, diff, scope, or intent change.

Evidence discipline

Always separate: fact | inference | recommendation | open-question | current-observed-law | documented-intent | explicit-user-target | proposed-law | contradicted-or-retired. Treat absent evidence as uncertainty, not permission.

Workflow

1. Fingerprint the repository

Repository kind, languages, build/test systems, deployment shape, dependency direction, subsystems, public-contract roots, entrypoints, local dialect. Architecture is a hypothesis backed by responsibilities and dependency direction, not directory names.

2. Build the system map

Trace representative flows: input/trigger -> parsing/routing -> orchestration -> domain transition -> persistence/integration -> output/effect. Record external boundaries, persistence/config roots, feedback loops, and delays.

3. Map authority and state

For important state and evidence, identify who may create, mutate, validate, certify, publish, transfer, consume, retire, and roll back it. Prioritize write paths, transitions, certificates, transactions, and rollback over readers or names.

4. Extract the behavioral model

Use the smallest correctness vocabulary that explains carriers, operations, observations, state classes, transitions, laws, non-laws, forbidden states, and projections. Do not turn incidental current behavior into doctrine.

5. Extract current and target laws

Every law records: doctrine status and normative authority; owner; accepted observations and counterexamples; current evidence and (when applicable) target authority; gap statement; proof obligations and proof surfaces. Never merge an observed law and a proposed repair law into one unlabelled row.

6. Extract owned invariants and boundaries

An invariant requires: owner, source of truth, initialization, preserving transitions, violating counterexamples, enforcement boundary, exception owner, proof. A boundary requires: accepted/rejected inputs, authority before/after, transferred state or evidence, proof.

7. Failure archaeology

Normalize local wounds into recurring law, authority, representation, boundary, or proof-shape failures. A negative route may be suspected, witnessed, canonical, or retired — only a current canonical projection may create a durable route exclusion.

8. Map proof

Distinguish proof design, executed current proof, historical proof, and manual/reviewer proof. Executed current proof records command, exit code, result reference, toolchain, target, artifact state, and verification time.

9. Resolve contradictions

Do not average incompatible claims. Resolve them, or preserve the contradiction, the stronger evidence, residual uncertainty, and materiality.

10. Route durable knowledge

Every durable active claim gets exactly one primary destination — prefer the strongest enforceable one:

code | type_or_representation | test_or_property | static_tool_or_linter | CI_gate
| repository_guidance (AGENTS.md/CLAUDE.md) | ADR_or_reference | negative_ledger
| repository_root_skill | focused_skill | retain_in_doctrine | reject

11. Optional skill portfolio

Shape: zero or one root repository skill, plus zero to five focused skills. No skill is required. Each candidate is an evidence-bearing decision, not a self-attested boolean; new candidates normally end as recommended_for_trial, with accepted reserved for empirical use evidence.

12. Test saturation

Stop when more search is unlikely to change a material decision: every required lane covered, no open route-changing search, no unresolved material contradiction, every durable active claim routed. Never claim exhaustive understanding.

Adaptive specialists (deep mode)

Only for unresolved route-changing questions, never just because mode is deep. Suggested waves: (1) cartographer + authority/state mapper; (2) behavioral-law miner / failure-forensics / proof mapper on identified surfaces; (3) portfolio skeptic after draft routing; (4) saturation auditor after the complete draft. Spawn read-only workers with your harness's parallel-agent mechanism (Claude Code Task / Codex custom agents); each gets a scoped assignment and returns one evidence-bearing packet; reject stale, wrong-scope, or out-of-authority material; synthesize yourself.

Persistence and handoff

Default output is conversational. Persist only when requested, to .codebase-doctrine/doctrine.yaml (local-exclude by default unless the user wants versioned doctrine). This skill recommends skills; it does not create them. After explicit authorization, hand a doctrine-bound skill brief to a skill-authoring pass.

Hard rules

• Read-only. Research discoverable facts before asking.
• No material doctrine without a locked intent capsule.
• No repository-derived invariant locked as user intent; no silent intent drift.
• Every durable active claim has exactly one primary route.
• Writes and transitions outrank reads for authority.
• No law without status, authority, counterexample, evidence, and proof posture.
• No invariant without owner, initialization, transitions, boundary, counterexample, and proof.
• No persistence or skill creation without explicit authorization.
• Never claim exhaustive understanding.