mpriatel Axiomatic Development
Axioms are precise, machine-readable architectural constraints stored in design_docs/axioms/. They are the primary source of truth for all design decisions. Every code change must be consistent with them.
Primary axiom source: design_docs/axioms/ (local files).
The axiom directory contains an INDEX.md that maps each axiom file to its domain and trigger conditions. Read design_docs/axioms/INDEX.md first to determine which files are relevant.
Modes
This skill operates in three modes. Select based on context:
| Mode | When to use | Axioms exist? |
|---|---|---|
| Develop | Default. Any code change in a codebase with axioms. | Yes |
| Initialize | User asks to create axioms for a codebase that has none. | No |
| Audit | User asks to check code against existing axioms for drift/gaps. | Yes |
For detailed Initialize and Audit procedures, see modes.md.
Develop Mode
The default mode. Used for all code changes when axioms already exist.
Step 1 — Read the axiom index
Read design_docs/axioms/INDEX.md to identify which axiom files apply based on the domain(s) the change touches. When uncertain, read more files rather than fewer.
Step 2 — Read the axiom files
Read each relevant file in full. Do not rely on memory or summaries from prior turns.
Step 3 — Plan with axioms as constraints
Design the implementation to satisfy all applicable axioms. If multiple approaches exist, prefer the one most consistent with axioms.
Step 4 — Cite axioms that influence decisions
When an axiom directly shapes a design choice, cite it inline:
Per
axioms_schema.md§3 (Multi-Tenancy Enforcement), this model inheritsTenantMixin.
Cite only when an axiom meaningfully influences the decision — not on every line.
Step 5 — Flag conflicts
If the requested change would violate an axiom:
- Stop before implementing.
- State which axiom (file, section, corollary) would be violated.
- Explain the conflict concisely.
- Ask the user how to proceed before writing any code.
Never silently violate an axiom.
Step 6 — Evaluate axiom maintenance (after completing a feature or refactor)
After completing a significant change, assess:
- New axiom needed? Does this change introduce a new architectural pattern or constraint not yet captured?
- Existing axiom outdated? Does this change invalidate or modify an existing axiom's assumptions?
- Corollary needed? Does this change reveal a non-obvious implication of an existing axiom?
Step 7 — Propose (do not write) axiom changes
If maintenance is needed:
- State what you would add, update, or remove.
- Draft the proposed axiom text following the format in axiom-format.md.
- Wait for user approval before writing to any axiom file.
Never modify axiom files without explicit user approval.
Context Management
These rules apply across all modes to ensure effective use of the LLM context window.
- Re-read, don't recall. Always read axiom files fresh from disk. Never rely on axiom content remembered from earlier in the conversation — it may be stale, truncated, or misremembered.
- One domain at a time. When working across multiple axiom domains (Initialize, Audit, or multi-domain Develop changes), complete one domain fully before moving to the next. Do not load all domains into context simultaneously.
- Use Plan mode for multi-domain changes. If a Develop-mode change touches 3+ axiom domains or has potential cross-domain conflicts, switch to Plan mode first. Outline which axioms apply and how they interact before writing code.
- Use subagents for parallel exploration. In Initialize (codebase survey) and Audit (code review), use explore subagents to analyze independent domains in parallel. Each subagent should return a structured summary, not raw code.
- Write artifacts incrementally. In long-running sessions (Initialize, Audit), write approved axiom files and present domain reports as you go. Do not accumulate everything for a single output at the end — earlier context will be lost.
- Summarize before moving on. After completing a domain, produce a brief summary of key findings or decisions. This summary persists in the conversation even if the raw analysis scrolls out of context.
Axiom Authoring Principles
Axioms are written for machines (LLM agents) first, humans second:
- Precise: No ambiguity. Each statement has exactly one interpretation.
- Declarative: State what MUST or MUST NOT be true, not how to achieve it.
- Testable: Each axiom implies a verifiable condition.
- Stable: Axioms change rarely. Prefer corollaries for implementation-specific guidance.
- Scoped: Each axiom file covers one domain. Cross-cutting concerns get their own file.
For the full axiom file format specification, see axiom-format.md.
Conflict Resolution
When a user's request conflicts with an axiom:
- The agent MUST surface the conflict before proceeding.
- The agent presents the axiom and the conflicting instruction.
- The user decides: comply with axiom, override with justification, or update the axiom.
- If the user overrides, note the deviation in the commit or PR description.
Axioms are not optional defaults — they are constraints that require explicit override.