COMPILER SKILL
Overview
Architectural compiler: FRS (immutable) → staging (INGEST) → DDD knowledge graph (ABSORB, 23 node types) → artifacts (Feature Specs, GitLab Issues, Test Plans, API Docs, topologies, changelogs). Enforces 30 LINT classes, role boundaries (BA/Agent/Developer/QA), consistency rules. Core: compile (not summarize), immutable sources, fail-fast (CNF- nodes), file SYN- back (3-bar quality gate), snapshot = RAM, Shadow QA in Flows (FEATs reference only), terminal states (rejected/superseded/deprecated), scenario gaps block COMPILE, developer signs TRUN before Gate 4.
Companions: SCHEMAS.md (quick node reference), node-definitions/ (complete node templates), OPERATIONS.md (procedure index), operations/ (detailed procedures), templates/FILESYSTEM.md (layout), templates/KARAPATHY.md (alignment), templates/TDD_VALIDATION.md (testing).
When to Use
- Ingest FRS → extract to ACT-/ENT-/CMD-/FLOW-/STATE- nodes
- Generate artifacts → Feature Specs, GitLab Issues, Test Plans, API docs
- Query architecture → module relationships, version deps, impact traces
- Resolve conflicts → CNF- (blocking) or DFB- (feedback)
- Milestone closure → 6-gate validation
- LINT audit → 28 debt classes
Symptoms: need FRS→impl traceability, version drift, duplicated Shadow QA, large home.md, deprecated refs still active.
When NOT to Use
- Free-form wiki editing → This skill enforces DDD structure. Use standard wiki editor for unstructured content.
- Bypass Business Analyst gates → Role boundaries are non-negotiable. See Role Boundaries table.
- Ingest monolithic FRS → Violates "one use case per document". Split first, then
ingest.
- Modify raw FRS files →
/raw_sources/ is immutable. Document corrections as SYN- nodes and submit via ingest --role dev --feedback.
- Implement without test sign-off → Even if feature works, TRUN with
sign_off_by is mandatory. See IMPLEMENT prerequisites in OPERATIONS.md.
- Quick typo fixes in sources → Any modification to raw sources requires SYN- + CNF flow, regardless of size.
- Rapid prototyping → This system is for production-grade knowledge graphs with BA gates. For throwaway exploration, use separate workspace.
Execution Workflow
Never guess steps. Always load the operation file before execution.
- Read SKILL.md — understand which command category applies
- Read OPERATIONS.md — decide specific operation from the index
- Load
operations/<OPERATION>.md — follow step-by-step procedure exactly
- Execute & log — append to
log.md, update snapshot.md, rebuild if dirty
- Verify preconditions — run Pre-Operation Checklist before any write operation
Key insight: Procedures live in operations/, not in SKILL.md. SKILL.md tells you when to use which command; OPERATIONS.md tells you which command file to load; the operation file tells you how.
Common Confusions
| Confusion |
Clarification |
query archaeology vs scoped query |
Archaeology is chronological evolution; scoped query is general synthesis. Both use query command: query archaeology <id> vs query --module M "question?" |
IMPLEMENT requires what |
Requires signed TRUN node (sign_off_by populated) AND status: pass. CI URL optional but recommended. Test pass alone ≠ sufficient. |
| CNF vs DFB |
CNF = blocking conflict between wiki nodes (logic, version drift, deprecation). DFB = developer feedback that wiki doesn't match reality. CNF halts compilation; DFB routes to BA for review. |
| Ephemeral vs durable artifacts |
Ephemeral (regenerate): TPLAN, TOPO. Durable (versioned): TRUN, APIDOC, CHGLOG. Ephemeral artifacts reference a wiki snapshot; stale ones must be regenerated. |
resolve dfb vs reject dfb |
Both in RESOLVE_DFB.md. Resolve = BA agrees, fixes wiki, closes DFB. Reject = BA disagrees, documents rationale, closes DFB. Both require BA blocks. |
| RECOVER is auto-triggered |
Never invoke RECOVER directly. BOOT auto-triggers it when dirty: true or last_compiled is stale. |
SUPERSEDE vs REJECT |
SUPERSEDE = new FEAT replaces old (both remain, linked). REJECT = FEAT terminal state with reason. Use supersede for replacements; reject for dead ends. |
SCHEMAS.md vs node-definitions/ |
SCHEMAS.md = quick lookup only (prefix, directory, one-line constraints). NEVER use it to create nodes. ALWAYS load the specific node-definitions/<TYPE>.md file (e.g., ACT.md, FEAT.md) for complete frontmatter template, body structure, examples, and common mistakes. |
INGEST vs ABSORB |
INGEST = fast, cheap, reversible — stages the FRS as metadata only; no DDD nodes written. ABSORB = compilation pass that writes DDD nodes; can halt mid-batch if a CNF changes the domain model, allowing earlier entries to be re-evaluated before resuming. Always run INGEST before ABSORB. Never skip ABSORB and expect nodes to exist. |
SYNTHESIZE vs saving a QUERY result |
QUERY produces ephemeral output; the agent may offer to file it. SYNTHESIZE is the explicit command to file a cross-cutting insight as a durable SYN- node. Before filing, the 3-bar quality gate must pass: (1) insight draws on ≥2 distinct source nodes, (2) connection is non-obvious, (3) claim is falsifiable/actionable. Agent must prompt BA before writing the node. |
ARCHAEOLOGY vs boot --brownfield |
query archaeology <id> = query-time chronological trace of a node or FRS (can run any session). boot --brownfield = one-time initialization procedure for existing codebases — scans source docs, extracts implicit nodes, builds baseline snapshot. Never use archaeology as a substitute for brownfield init. |
generate testrun produces unsigned TRUN |
generate testrun creates a TRUN with pipeline_status populated but sign_off_by empty. The developer must separately run sign <trun-id> to satisfy Gate 4. A passing pipeline alone does not unlock IMPLEMENT. |
What If Something Fails? — Troubleshooting
| Failure Symptom |
Likely Cause |
Fix |
| BOOT: "dirty: true" |
Previous session crashed or interrupted |
Let RECOVER run automatically. Do NOT manually edit snapshot.md. |
| COMPILE: "open CNFs pending" |
Version drift, logic conflict, or deprecation citation unresolved |
Resolve CNFs first via RESOLVE CNF (BA required). Cannot proceed with blocking conflicts. |
| COMPILE: "scenario gaps present" |
One or more FLOWs in the target module have unfilled scenario_gap slots |
BA must supply missing scenario slots before COMPILE can proceed. scenario_gap_present is a hard gate, not a warning. |
LINT: shadow_qa_drift |
FEAT copied Shadow QA text instead of wikilinking |
Restore wikilink reference: "See FLOW-{id} → ## Shadow QA". Delete copied scenarios. |
LINT: stale_synthesis |
SYN- node references source nodes that have since been updated |
Re-run SYNTHESIZE or supersede the stale SYN- node. BA must confirm whether the insight still holds. |
LINT: index_entry_missing |
Node file exists in docs/ but has no entry in index.md |
Add the missing entry to index.md. Every INGEST/ABSORB/SYNTHESIZE must write through to index.md as its final step. |
| IMPLEMENT: "no signed TRUN" |
Test run completed but developer didn't run sign <trun-id> |
Run sign <trun-id> to populate sign_off_by. Pipeline pass alone does not satisfy Gate 4. |
| QUERY: slow (>5s) |
home.md >150 nodes, still in scale_mode: index |
Switch to scale_mode: search in snapshot.md. Use scoped queries (--module M) instead of full-wiki. |
| INGEST: monolith detected |
FRS covers multiple independent use cases |
Split FRS into separate documents per use case. Create CNF if BA decides to proceed anyway. |
| ABSORB: halted mid-batch |
A CNF was raised during compilation that affects earlier entries in the batch |
Resolve the CNF (BA required), then re-run absorb from the halted entry. Earlier-absorbed nodes are safe; partial batch is rolled back. |
| GENERATE: "stale TPLAN" |
TPLAN wiki_snapshot_ref predates covered node modifications |
Regenerate TPLAN first. TRUN must use current TPLAN. |
| MILESTONE CLOSE: gate failures |
One or more 6-gates not passed (CNFs, LINT, FEAT status) |
Fix root cause (resolve CNFs, ensure all FEAT implemented/rejected/superseded, LINT clean). |
Directory Structure
The compiler skill uses three complementary documentation layers:
SCHEMAS.md — Quick reference index. Use to lookup node type prefix, directory, and key constraints in one glance.node-definitions/ — Complete node type templates (ACT.md, ENT.md, CMD.md, FLOW.md, etc.). LOAD THESE when creating or editing specific node instances. Each contains full frontmatter template, body structure, schema rules, common mistakes, and runnable examples.templates/ — Supporting documents (FILESYSTEM.md, KARAPATHY.md, prompts, validation docs). Use for guidelines, workflows, and procedural documentation.
Never confuse these: Node templates are always in node-definitions/, not templates/. SCHEMAS.md is just an index; it does not contain complete templates.
Decision Flowcharts
Greenfield vs Brownfield
digraph g { existing_docs -> greenfield [label=no]; existing_docs -> brownfield [label=yes]; }
Greenfield: Create skeleton, stub snapshot, await first FRS (§10).
Brownfield: Archaeology pass → extract nodes → flag contradictions as CNF-.
Version Increment
digraph v { "Breaking change" -> major; additive -> minor; "prose-only" -> patch; }
Major (breaking): rename/remove field, change type, restructure state machine, remove transition, revise SLA materially. Triggers deprecation propagation for ENT/CMD.
Minor (additive): new attribute, new scenario, new constraint without breaking, new linked node.
Patch (prose-only): typo fix, clarification with no behavioral change, reformatting.
Common Mistakes
| Mistake |
What goes wrong |
| Monolithic FRS |
Violates "One FRS Per Use Case" |
| Shadow QA duplication |
FEAT copies Flow tests → drift |
| Version drift unflagged |
CMD/ENT version > FLOW min_version → breakage |
| Deprecation bypass |
No CNF- for references |
| Raw source modification |
Violates immutability |
| CNF resolution without BA |
BA-gate bypass |
| home.md blowout |
>150 nodes → slow queries |
| IMPLEMENT without TRUN |
No test evidence |
| LINT as warning |
Debt accumulates |
| Milestone close with open CNFs |
6-gate violation |
| Skipping ABSORB after INGEST |
Staging entries exist but no DDD nodes written; downstream COMPILE silently has nothing to aggregate |
| Filing SYN- without 3-bar check |
Low-quality insight pollutes synthesis layer; stale_synthesis lint fires later |
| Omitting index.md entry on node creation |
index_entry_missing lint; node invisible to QUERY scoped searches |
| COMPILE with open scenario gaps |
BA-supplied scenario slots missing; BEA unblocks prematurely → untestable flows |
| Architect signs TRUN |
Role boundary bypass; only Developer may populate sign_off_by |
Red Flags — STOP and Verify
MUST NOT proceed. HALT and create CNF- with conflict_class: rule_violation if pressured.
- ❌ Modify
/raw_sources/ — IMMUTABLE (see Overview)
- ❌ Skip deprecation propagation
- ❌ Resolve CNF- without BA block
- ❌ Bypass DFB escalation (7+ days)
- ❌ Copy Shadow QA into FEAT
- ❌ Set
implemented without signed TRUN
- ❌ Sign TRUN as BA or architect — only Developer role may populate
sign_off_by
- ❌ Ignore home.md scale (>150 nodes)
- ❌ Treat version drift as "compatible"
- ❌ Proceed with monolith FRS
- ❌ "Quick fix" typo in source
- ❌ MILESTONE CLOSE with open CNFs
- ❌ Continue after LINT failures
- ❌ Begin COMPILE with
scenario_gap_present on any FLOW in the target module — hard gate, not a warning
- ❌ File SYN- node without passing the 3-bar quality gate (two distinct nodes, non-obvious connection, falsifiable/actionable)
- ❌ File SYN- node without prompting BA first
- ❌ Write a node to
docs/ without a corresponding index.md entry (index_entry_missing)
- ❌ Run ABSORB without prior INGEST for the same FRS — staging entry must exist before compilation
- ❌ Use
query archaeology as a substitute for boot --brownfield brownfield initialization
Violating letter = violating spirit. All pressures (time, authority, sunk cost, exhaustion) → CNF gating.
Common Rationalizations — Reality Check
When under pressure, agents rationalize violations. Every excuse below is a STOP signal:
| Excuse |
Reality |
| "Just a typo fix" |
IMMUTABILITY applies to all changes, regardless of size. Create SYN + CNF for BA to handle. |
| "Backward compatible enough" |
Version drift is binary: new_version > pinned_min_version = blocking CNF. |
| "Too much BA work this sprint" |
Technical debt left unaddressed compounds. CNF must be created NOW, not later. |
| "Feature works in production" |
TRUN is the gate. No sign-off = cannot set implemented status. Milestone closure integrity fails. |
| "Makes FEAT more self-contained" |
Shadow QA drift creates stale test scenarios. Reference only; duplication forbidden. |
| "It's well-written, splitting would create more work" |
Monolithic FRS violates one-use-case-per-document principle. CNF required regardless of doc quality. |
| "It's obvious, no need to wait for BA" |
CNF resolution is BA-gated by design. Agent cannot unilaterally decide "obvious" conflicts. |
| "Minor, developer overthinking" |
DFB nodes require BA resolution regardless of perceived severity. 7+ days = automatic escalation. |
| "Still readable, user didn't ask to switch" |
Scale threshold is a hard rule at ~150 nodes, not a preference. Switch to search mode automatically. |
| "Flag it in description but no CNF needed" |
Version drift is a blocking event. Notes in description do not substitute for CNF creation. |
| "Status change is enough" |
Supersede requires bidirectional linking: status: superseded + superseded_by populated. Traceability mandatory. |
| "Minor, can carry over" |
Milestone close requires zero open CNFs (6-gate rule). No exceptions for "minor" conflicts. |
| "ABSORB is just INGEST by another name" |
INGEST stages only. ABSORB compiles to DDD nodes and has rollback semantics. Collapsing them loses the mid-batch conflict recovery guarantee. |
| "Insight is obvious, no need for 3-bar check" |
The quality gate exists to prevent low-signal SYN- nodes from polluting the synthesis layer. Agent cannot unilaterally declare an insight passes — prompt BA. |
| "I'll add the index.md entry later" |
A node absent from index.md is invisible to scoped QUERY. index_entry_missing is a lint violation. Write-through is mandatory on every node creation operation. |
| "Scenario gaps are minor, we can design around them" |
Scenario gaps are a hard gate. BEA cannot begin DESIGN until BA supplies all missing scenario slots. There is no designing around absent acceptance criteria. |
| "Pipeline passed, that's sign-off enough" |
pipeline_status: pass and sign_off_by are separate fields for separate purposes. Developer signature is the human attestation Gate 4 requires. |
System Invariants
These non-negotiable constraints govern all operations:
- Immutable sources:
/raw_sources/ is read-only. All corrections via SYN- nodes + BA approval.
- Snapshot = RAM:
snapshot.md rebuilt from filesystem after every write; never trust in-memory state.
- Dirty flag gating: Any write sets
dirty: true. BOOT auto-triggers RECOVER if dirty.
- CNF = blocking: Any rule violation creates CNF- node. Must be resolved before proceeding.
- BA gates: CNF resolution, DFB rejection, milestone closure, IMPLEMENT trigger require BA blocks.
- Role boundaries: Agent cannot perform BA functions; Developer/QA cannot approve FEATs; only Developer signs TRUN.
- Terminal states:
rejected, superseded, deprecated are final — no further edits allowed.
- Traceability chain: Every node must link to source FRS; every change must be logged.
- INGEST before ABSORB: INGEST stages only. ABSORB compiles. Never run ABSORB without a prior INGEST for the same FRS.
- index.md write-through: Every INGEST, ABSORB, and SYNTHESIZE operation must write an entry to
index.md as its final step before updating snapshot.md. A node absent from index.md is a lint violation (index_entry_missing).
- Scenario gap hard gate: COMPILE cannot begin for a module with any
scenario_gap on its FLOWs. BA must supply all missing scenarios first.
- SYNTHESIZE 3-bar gate: A SYN- node may only be filed if: (1) ≥2 distinct source nodes, (2) non-obvious connection, (3) falsifiable/actionable claim. Agent must prompt BA before filing.
Violating letter = violating spirit. See operations/BOOT.md for pre-operation checklist and detailed procedures.
Role Boundaries
| Role |
CAN |
CANNOT |
| Business Analyst (BA) |
Write FRS, resolve CNF-, approve/reject FEAT, trigger IMPLEMENT/SUPERSEDE, close milestones, define modules, resolve/reject DFB |
Modify DDD nodes (except via CNF resolution) |
| Backend Architect |
INGEST, COMPILE, QUERY, LINT, ISSUE, IMPLEMENT/SUPERSEDE/RESOLVE (exec), GENERATE, ARCHAEOLOGY, MILESTONE CLOSE |
Write FRS, modify raw sources, approve FEAT, resolve CNF/DFB (that's BA), name classes/files |
| Developer |
INGEST --role dev (SYN-), INGEST --role dev --feedback (DFB-), request GENERATE, populate TRUN, sign off TRUN |
Modify FRS, approve FEAT, close CNF-, close/reject DFB (BA only) |
Key principles:
- BA gates: CNF resolution, DFB resolution/rejection, milestone closure, FEAT approval
- Backend Architect executes procedures but cannot bypass BA gates
- Developers generate test evidence (TRUN) but cannot approve features
- All modifications to raw sources are prohibited (immutability)
- DFB escalation after 7 days automatic regardless of role
Testing & Validation
Pressure-tested with 23 scenarios (templates/test-pressure-scenarios.md). 3 RED-GREEN-REFACTOR iterations closed 12 rationalizations. 100% compliance achieved under combined pressures (time + authority + exhaustion). See templates/TDD_VALIDATION.md. Iron Law satisfied: validated against failures before deployment.
Reference Material
Quick indexes (load first):
SCHEMAS.md — Node type quick reference table (prefix, directory, purpose). WARNING: For lookup only. NEVER use to create nodes.OPERATIONS.md — Command procedure index
Complete node templates (load when creating/validating specific nodes):
node-definitions/{ACT,ENT,CMD,FLOW,STATE,DEC,INT,VM,CNF,SYN,FEAT,TRUN,APIDOC,CHGLOG,CAP,ARCH,TOPO,GLOSS,DFB,CONV,SNAPSHOT,MODULES}.md — Full frontmatter, body structure, examples, common mistakes. THESE ARE YOUR SOURCE OF TRUTH for node creation.
Procedures & guidelines:
operations/ — Detailed command procedures (indexed by OPERATIONS.md)templates/FILESYSTEM.md — Directory layouttemplates/KARAPATHY.md — Alignment guidelinestemplates/TDD_VALIDATION.md — Test pressure scenarios & validation resultstemplates/test-pressure-scenarios.md — Scenario definitionstemplates/FRS.md — FRS authoring template
Load heavy references only when needed.
Keywords
FRS ingestion, DDD nodes, knowledge graph, Feature Specs, GitLab Issues, test plans, topology, changelog, apidoc, LINT, version bump, deprecation propagation, CNF conflict, DFB feedback, milestone closure, immutable sources, Shadow QA, version drift, monolith FRS, scale mode, snapshot, RECOVER, BA gates, role boundaries, terminal states, traceability chain.
LINT classes: missing_actor, floating_convention, shadow_qa_drift, decomposition_violation, missing_module_registration, version_drift, deprecated_citation, broken_state, logic_conflict, scale_threshold, dirty_snapshot, unclosed_cnf, dfb_escalation, trun_signoff_missing, apidoc_overwrite, changelog_audience_missing, home.md_blowout, linter_failed, milestone_gate_violation, raw_source_modification, immutability_violation, role_boundary_bypass, terminal_state_bypass, traceability_gap, deprecation_propagation_skipped, shadow_qa_duplication, schema_mismatch, linked_node_missing, index_entry_missing, scenario_gap_present.
Error patterns: conflict_class: rule_violation, conflict_class: deprecated_citation, conflict_class: version_drift, conflict_class: decomposition_violation, CNF resolution requires BA block, DFB escalation 7 days, home.md >150 nodes scale_mode:search, TRUN sign-off required, ephemeral vs durable artifacts, pending_ingests, open_conflicts, open_feedback, dirty: true, last_compiled older than log.md, scenario_gaps: N blocking COMPILE, 3-bar quality gate failed, index_entry_missing on node creation, absorb halted mid-batch, brownfield init required.
1---2name: compiler3description: Use for FRS-to-DDD compilation, artifact generation, architecture queries, conflict resolution (CNF/DFB), or milestone closure. Symptoms: need traceability from FRS to Feature Specs, version drift detection, Shadow QA duplication prevention, non-monolithic FRS enforcement, or home.md >150 nodes. Keywords: FRS ingestion, ABSORB compilation pass, DDD nodes (ACT/ENT/CMD/FLOW/STATE), CNF blocking, DFB feedback, version bump rules, deprecation propagation, 6-gate milestone closure, immutable sources, Shadow QA wikilinks, LINT debt (30 classes), TRUN sign-off required, SYNTHESIZE 3-bar quality gate, brownfield init, scenario gap hard gate.4---56# COMPILER SKILL78## Overview910Architectural compiler: FRS (immutable) → staging (INGEST) → DDD knowledge graph (ABSORB, 23 node types) → artifacts (Feature Specs, GitLab Issues, Test Plans, API Docs, topologies, changelogs). Enforces 30 LINT classes, role boundaries (BA/Agent/Developer/QA), consistency rules. Core: compile (not summarize), immutable sources, fail-fast (CNF- nodes), file SYN- back (3-bar quality gate), snapshot = RAM, Shadow QA in Flows (FEATs reference only), terminal states (rejected/superseded/deprecated), scenario gaps block COMPILE, developer signs TRUN before Gate 4.1112**Companions:** `SCHEMAS.md` (quick node reference), `node-definitions/` (complete node templates), `OPERATIONS.md` (procedure index), `operations/` (detailed procedures), `templates/FILESYSTEM.md` (layout), `templates/KARAPATHY.md` (alignment), `templates/TDD_VALIDATION.md` (testing).1314---1516## When to Use1718- **Ingest FRS** → extract to ACT-/ENT-/CMD-/FLOW-/STATE- nodes19- **Generate artifacts** → Feature Specs, GitLab Issues, Test Plans, API docs20- **Query architecture** → module relationships, version deps, impact traces21- **Resolve conflicts** → CNF- (blocking) or DFB- (feedback)22- **Milestone closure** → 6-gate validation23- **LINT audit** → 28 debt classes2425**Symptoms:** need FRS→impl traceability, version drift, duplicated Shadow QA, large home.md, deprecated refs still active.2627---2829## When NOT to Use3031- **Free-form wiki editing** → This skill enforces DDD structure. Use standard wiki editor for unstructured content.32- **Bypass Business Analyst gates** → Role boundaries are non-negotiable. See Role Boundaries table.33- **Ingest monolithic FRS** → Violates "one use case per document". Split first, then `ingest`.34- **Modify raw FRS files** → `/raw_sources/` is immutable. Document corrections as SYN- nodes and submit via `ingest --role dev --feedback`.35- **Implement without test sign-off** → Even if feature works, TRUN with `sign_off_by` is mandatory. See `IMPLEMENT` prerequisites in OPERATIONS.md.36- **Quick typo fixes in sources** → Any modification to raw sources requires SYN- + CNF flow, regardless of size.37- **Rapid prototyping** → This system is for production-grade knowledge graphs with BA gates. For throwaway exploration, use separate workspace.3839---4041## Execution Workflow4243**Never guess steps. Always load the operation file before execution.**44451. **Read SKILL.md** — understand which command category applies462. **Read OPERATIONS.md** — decide specific operation from the index473. **Load `operations/<OPERATION>.md`** — follow step-by-step procedure exactly484. **Execute & log** — append to `log.md`, update `snapshot.md`, rebuild if dirty495. **Verify preconditions** — run Pre-Operation Checklist before any write operation5051**Key insight:** Procedures live in `operations/`, not in SKILL.md. SKILL.md tells you **when** to use which command; OPERATIONS.md tells you **which** command file to load; the operation file tells you **how**.5253---5455## Common Confusions5657| Confusion | Clarification |58|-----------|---------------|59| `query archaeology` vs scoped query | Archaeology is chronological evolution; scoped query is general synthesis. Both use `query` command: `query archaeology <id>` vs `query --module M "question?"` |60| `IMPLEMENT` requires what | Requires **signed TRUN node** (`sign_off_by` populated) **AND** `status: pass`. CI URL optional but recommended. Test pass alone ≠ sufficient. |61| CNF vs DFB | **CNF** = blocking conflict between wiki nodes (logic, version drift, deprecation). **DFB** = developer feedback that wiki doesn't match reality. CNF halts compilation; DFB routes to BA for review. |62| Ephemeral vs durable artifacts | **Ephemeral** (regenerate): TPLAN, TOPO. **Durable** (versioned): TRUN, APIDOC, CHGLOG. Ephemeral artifacts reference a wiki snapshot; stale ones must be regenerated. |63| `resolve dfb` vs `reject dfb` | Both in `RESOLVE_DFB.md`. **Resolve** = BA agrees, fixes wiki, closes DFB. **Reject** = BA disagrees, documents rationale, closes DFB. Both require BA blocks. |64| RECOVER is auto-triggered | Never invoke `RECOVER` directly. `BOOT` auto-triggers it when `dirty: true` or `last_compiled` is stale. |65| `SUPERSEDE` vs `REJECT` | **SUPERSEDE** = new FEAT replaces old (both remain, linked). **REJECT** = FEAT terminal state with reason. Use supersede for replacements; reject for dead ends. |66| `SCHEMAS.md` vs `node-definitions/` | **SCHEMAS.md** = quick lookup only (prefix, directory, one-line constraints). **NEVER** use it to create nodes. **ALWAYS** load the specific `node-definitions/<TYPE>.md` file (e.g., `ACT.md`, `FEAT.md`) for complete frontmatter template, body structure, examples, and common mistakes. |67| `INGEST` vs `ABSORB` | **INGEST** = fast, cheap, reversible — stages the FRS as metadata only; no DDD nodes written. **ABSORB** = compilation pass that writes DDD nodes; can halt mid-batch if a CNF changes the domain model, allowing earlier entries to be re-evaluated before resuming. Always run INGEST before ABSORB. Never skip ABSORB and expect nodes to exist. |68| `SYNTHESIZE` vs saving a QUERY result | **QUERY** produces ephemeral output; the agent may offer to file it. **SYNTHESIZE** is the explicit command to file a cross-cutting insight as a durable SYN- node. Before filing, the 3-bar quality gate must pass: (1) insight draws on ≥2 distinct source nodes, (2) connection is non-obvious, (3) claim is falsifiable/actionable. Agent must prompt BA before writing the node. |69| `ARCHAEOLOGY` vs `boot --brownfield` | **`query archaeology <id>`** = query-time chronological trace of a node or FRS (can run any session). **`boot --brownfield`** = one-time initialization procedure for existing codebases — scans source docs, extracts implicit nodes, builds baseline snapshot. Never use archaeology as a substitute for brownfield init. |70| `generate testrun` produces unsigned TRUN | `generate testrun` creates a TRUN with `pipeline_status` populated but `sign_off_by` **empty**. The developer must separately run `sign <trun-id>` to satisfy Gate 4. A passing pipeline alone does not unlock IMPLEMENT. |7172---7374## What If Something Fails? — Troubleshooting7576| Failure Symptom | Likely Cause | Fix |77|-----------------|--------------|-----|78| **BOOT:** "dirty: true" | Previous session crashed or interrupted | Let RECOVER run automatically. Do NOT manually edit `snapshot.md`. |79| **COMPILE:** "open CNFs pending" | Version drift, logic conflict, or deprecation citation unresolved | Resolve CNFs first via `RESOLVE CNF` (BA required). Cannot proceed with blocking conflicts. |80| **COMPILE:** "scenario gaps present" | One or more FLOWs in the target module have unfilled `scenario_gap` slots | BA must supply missing scenario slots before COMPILE can proceed. `scenario_gap_present` is a hard gate, not a warning. |81| **LINT:** `shadow_qa_drift` | FEAT copied Shadow QA text instead of wikilinking | Restore wikilink reference: "See FLOW-{id} → ## Shadow QA". Delete copied scenarios. |82| **LINT:** `stale_synthesis` | SYN- node references source nodes that have since been updated | Re-run SYNTHESIZE or supersede the stale SYN- node. BA must confirm whether the insight still holds. |83| **LINT:** `index_entry_missing` | Node file exists in `docs/` but has no entry in `index.md` | Add the missing entry to `index.md`. Every INGEST/ABSORB/SYNTHESIZE must write through to `index.md` as its final step. |84| **IMPLEMENT:** "no signed TRUN" | Test run completed but developer didn't run `sign <trun-id>` | Run `sign <trun-id>` to populate `sign_off_by`. Pipeline pass alone does not satisfy Gate 4. |85| **QUERY:** slow (>5s) | `home.md` >150 nodes, still in `scale_mode: index` | Switch to `scale_mode: search` in `snapshot.md`. Use scoped queries (`--module M`) instead of full-wiki. |86| **INGEST:** monolith detected | FRS covers multiple independent use cases | Split FRS into separate documents per use case. Create CNF if BA decides to proceed anyway. |87| **ABSORB:** halted mid-batch | A CNF was raised during compilation that affects earlier entries in the batch | Resolve the CNF (BA required), then re-run `absorb` from the halted entry. Earlier-absorbed nodes are safe; partial batch is rolled back. |88| **GENERATE:** "stale TPLAN" | TPLAN `wiki_snapshot_ref` predates covered node modifications | Regenerate TPLAN first. TRUN must use current TPLAN. |89| **MILESTONE CLOSE:** gate failures | One or more 6-gates not passed (CNFs, LINT, FEAT status) | Fix root cause (resolve CNFs, ensure all FEAT `implemented/rejected/superseded`, LINT clean). |9091---9293## Directory Structure9495The compiler skill uses three complementary documentation layers:9697- **`SCHEMAS.md`** — Quick reference index. Use to lookup node type prefix, directory, and key constraints in one glance.98- **`node-definitions/`** — Complete node type templates (ACT.md, ENT.md, CMD.md, FLOW.md, etc.). **LOAD THESE** when creating or editing specific node instances. Each contains full frontmatter template, body structure, schema rules, common mistakes, and runnable examples.99- **`templates/`** — Supporting documents (FILESYSTEM.md, KARAPATHY.md, prompts, validation docs). Use for guidelines, workflows, and procedural documentation.100101**Never confuse these:** Node templates are always in `node-definitions/`, not `templates/`. SCHEMAS.md is just an index; it does not contain complete templates.102103---104105106## Decision Flowcharts107108### Greenfield vs Brownfield109110```dot111digraph g { existing_docs -> greenfield [label=no]; existing_docs -> brownfield [label=yes]; }112```113114**Greenfield:** Create skeleton, stub snapshot, await first FRS (§10).115**Brownfield:** Archaeology pass → extract nodes → flag contradictions as CNF-.116117### Version Increment118119```dot120digraph v { "Breaking change" -> major; additive -> minor; "prose-only" -> patch; }121```122123**Major** (breaking): rename/remove field, change type, restructure state machine, remove transition, revise SLA materially. Triggers deprecation propagation for ENT/CMD. 124**Minor** (additive): new attribute, new scenario, new constraint without breaking, new linked node. 125**Patch** (prose-only): typo fix, clarification with no behavioral change, reformatting.126127---128129## Common Mistakes130131| Mistake | What goes wrong |132|---------|----------------|133| Monolithic FRS | Violates "One FRS Per Use Case" |134| Shadow QA duplication | FEAT copies Flow tests → drift |135| Version drift unflagged | CMD/ENT version > FLOW min_version → breakage |136| Deprecation bypass | No CNF- for references |137| Raw source modification | Violates immutability |138| CNF resolution without BA | BA-gate bypass |139| home.md blowout | >150 nodes → slow queries |140| IMPLEMENT without TRUN | No test evidence |141| LINT as warning | Debt accumulates |142| Milestone close with open CNFs | 6-gate violation |143| Skipping ABSORB after INGEST | Staging entries exist but no DDD nodes written; downstream COMPILE silently has nothing to aggregate |144| Filing SYN- without 3-bar check | Low-quality insight pollutes synthesis layer; stale_synthesis lint fires later |145| Omitting index.md entry on node creation | `index_entry_missing` lint; node invisible to QUERY scoped searches |146| COMPILE with open scenario gaps | BA-supplied scenario slots missing; BEA unblocks prematurely → untestable flows |147| Architect signs TRUN | Role boundary bypass; only Developer may populate `sign_off_by` |148149---150151## Red Flags — STOP and Verify152153**MUST NOT proceed. HALT and create CNF- with `conflict_class: rule_violation` if pressured.**154155- ❌ Modify `/raw_sources/` — **IMMUTABLE** (see Overview)156- ❌ Skip deprecation propagation157- ❌ Resolve CNF- without BA block158- ❌ Bypass DFB escalation (7+ days)159- ❌ Copy Shadow QA into FEAT160- ❌ Set `implemented` without signed TRUN161- ❌ Sign TRUN as BA or architect — only Developer role may populate `sign_off_by`162- ❌ Ignore home.md scale (>150 nodes)163- ❌ Treat version drift as "compatible"164- ❌ Proceed with monolith FRS165- ❌ "Quick fix" typo in source166- ❌ MILESTONE CLOSE with open CNFs167- ❌ Continue after LINT failures168- ❌ Begin COMPILE with `scenario_gap_present` on any FLOW in the target module — hard gate, not a warning169- ❌ File SYN- node without passing the 3-bar quality gate (two distinct nodes, non-obvious connection, falsifiable/actionable)170- ❌ File SYN- node without prompting BA first171- ❌ Write a node to `docs/` without a corresponding `index.md` entry (`index_entry_missing`)172- ❌ Run ABSORB without prior INGEST for the same FRS — staging entry must exist before compilation173- ❌ Use `query archaeology` as a substitute for `boot --brownfield` brownfield initialization174175**Violating letter = violating spirit.** All pressures (time, authority, sunk cost, exhaustion) → CNF gating.176177---178179## Common Rationalizations — Reality Check180181When under pressure, agents rationalize violations. Every excuse below is a STOP signal:182183| Excuse | Reality |184|--------|---------|185| "Just a typo fix" | IMMUTABILITY applies to all changes, regardless of size. Create SYN + CNF for BA to handle. |186| "Backward compatible enough" | Version drift is binary: new_version > pinned_min_version = blocking CNF. |187| "Too much BA work this sprint" | Technical debt left unaddressed compounds. CNF must be created NOW, not later. |188| "Feature works in production" | TRUN is the gate. No sign-off = cannot set implemented status. Milestone closure integrity fails. |189| "Makes FEAT more self-contained" | Shadow QA drift creates stale test scenarios. Reference only; duplication forbidden. |190| "It's well-written, splitting would create more work" | Monolithic FRS violates one-use-case-per-document principle. CNF required regardless of doc quality. |191| "It's obvious, no need to wait for BA" | CNF resolution is BA-gated by design. Agent cannot unilaterally decide "obvious" conflicts. |192| "Minor, developer overthinking" | DFB nodes require BA resolution regardless of perceived severity. 7+ days = automatic escalation. |193| "Still readable, user didn't ask to switch" | Scale threshold is a hard rule at ~150 nodes, not a preference. Switch to search mode automatically. |194| "Flag it in description but no CNF needed" | Version drift is a blocking event. Notes in description do not substitute for CNF creation. |195| "Status change is enough" | Supersede requires bidirectional linking: `status: superseded` + `superseded_by` populated. Traceability mandatory. |196| "Minor, can carry over" | Milestone close requires zero open CNFs (6-gate rule). No exceptions for "minor" conflicts. |197| "ABSORB is just INGEST by another name" | INGEST stages only. ABSORB compiles to DDD nodes and has rollback semantics. Collapsing them loses the mid-batch conflict recovery guarantee. |198| "Insight is obvious, no need for 3-bar check" | The quality gate exists to prevent low-signal SYN- nodes from polluting the synthesis layer. Agent cannot unilaterally declare an insight passes — prompt BA. |199| "I'll add the index.md entry later" | A node absent from index.md is invisible to scoped QUERY. `index_entry_missing` is a lint violation. Write-through is mandatory on every node creation operation. |200| "Scenario gaps are minor, we can design around them" | Scenario gaps are a hard gate. BEA cannot begin DESIGN until BA supplies all missing scenario slots. There is no designing around absent acceptance criteria. |201| "Pipeline passed, that's sign-off enough" | `pipeline_status: pass` and `sign_off_by` are separate fields for separate purposes. Developer signature is the human attestation Gate 4 requires. |202203---204205## System Invariants206207These non-negotiable constraints govern all operations:208209- **Immutable sources:** `/raw_sources/` is read-only. All corrections via SYN- nodes + BA approval.210- **Snapshot = RAM:** `snapshot.md` rebuilt from filesystem after every write; never trust in-memory state.211- **Dirty flag gating:** Any write sets `dirty: true`. BOOT auto-triggers RECOVER if dirty.212- **CNF = blocking:** Any rule violation creates CNF- node. Must be resolved before proceeding.213- **BA gates:** CNF resolution, DFB rejection, milestone closure, IMPLEMENT trigger require BA blocks.214- **Role boundaries:** Agent cannot perform BA functions; Developer/QA cannot approve FEATs; only Developer signs TRUN.215- **Terminal states:** `rejected`, `superseded`, `deprecated` are final — no further edits allowed.216- **Traceability chain:** Every node must link to source FRS; every change must be logged.217- **INGEST before ABSORB:** INGEST stages only. ABSORB compiles. Never run ABSORB without a prior INGEST for the same FRS.218- **index.md write-through:** Every INGEST, ABSORB, and SYNTHESIZE operation must write an entry to `index.md` as its final step before updating `snapshot.md`. A node absent from `index.md` is a lint violation (`index_entry_missing`).219- **Scenario gap hard gate:** COMPILE cannot begin for a module with any `scenario_gap` on its FLOWs. BA must supply all missing scenarios first.220- **SYNTHESIZE 3-bar gate:** A SYN- node may only be filed if: (1) ≥2 distinct source nodes, (2) non-obvious connection, (3) falsifiable/actionable claim. Agent must prompt BA before filing.221222**Violating letter = violating spirit.** See `operations/BOOT.md` for pre-operation checklist and detailed procedures.223224---225226## Role Boundaries227228| Role | CAN | CANNOT |229|------|-----|--------|230| **Business Analyst (BA)** | Write FRS, resolve CNF-, approve/reject FEAT, trigger IMPLEMENT/SUPERSEDE, close milestones, define modules, resolve/reject DFB | Modify DDD nodes (except via CNF resolution) |231| **Backend Architect** | INGEST, COMPILE, QUERY, LINT, ISSUE, IMPLEMENT/SUPERSEDE/RESOLVE (exec), GENERATE, ARCHAEOLOGY, MILESTONE CLOSE | Write FRS, modify raw sources, approve FEAT, resolve CNF/DFB (that's BA), name classes/files |232| **Developer** | INGEST --role dev (SYN-), INGEST --role dev --feedback (DFB-), request GENERATE, populate TRUN, sign off TRUN | Modify FRS, approve FEAT, close CNF-, close/reject DFB (BA only) |233234**Key principles:**235- BA gates: CNF resolution, DFB resolution/rejection, milestone closure, FEAT approval236- Backend Architect executes procedures but cannot bypass BA gates237- Developers generate test evidence (TRUN) but cannot approve features238- All modifications to raw sources are prohibited (immutability)239- DFB escalation after 7 days automatic regardless of role240241---242243## Testing & Validation244245Pressure-tested with 23 scenarios (`templates/test-pressure-scenarios.md`). 3 RED-GREEN-REFACTOR iterations closed 12 rationalizations. 100% compliance achieved under combined pressures (time + authority + exhaustion). See `templates/TDD_VALIDATION.md`. **Iron Law satisfied:** validated against failures before deployment.246247---248249## Reference Material250251**Quick indexes (load first):**252- `SCHEMAS.md` — Node type quick reference table (prefix, directory, purpose). **WARNING:** For lookup only. **NEVER** use to create nodes.253- `OPERATIONS.md` — Command procedure index254255**Complete node templates (load when creating/validating specific nodes):**256- `node-definitions/{ACT,ENT,CMD,FLOW,STATE,DEC,INT,VM,CNF,SYN,FEAT,TRUN,APIDOC,CHGLOG,CAP,ARCH,TOPO,GLOSS,DFB,CONV,SNAPSHOT,MODULES}.md` — Full frontmatter, body structure, examples, common mistakes. **THESE ARE YOUR SOURCE OF TRUTH** for node creation.257258**Procedures & guidelines:**259- `operations/` — Detailed command procedures (indexed by OPERATIONS.md)260- `templates/FILESYSTEM.md` — Directory layout261- `templates/KARAPATHY.md` — Alignment guidelines262- `templates/TDD_VALIDATION.md` — Test pressure scenarios & validation results263- `templates/test-pressure-scenarios.md` — Scenario definitions264- `templates/FRS.md` — FRS authoring template265266Load heavy references only when needed.267268---269270## Keywords271272FRS ingestion, DDD nodes, knowledge graph, Feature Specs, GitLab Issues, test plans, topology, changelog, apidoc, LINT, version bump, deprecation propagation, CNF conflict, DFB feedback, milestone closure, immutable sources, Shadow QA, version drift, monolith FRS, scale mode, snapshot, RECOVER, BA gates, role boundaries, terminal states, traceability chain.273274**LINT classes:** `missing_actor`, `floating_convention`, `shadow_qa_drift`, `decomposition_violation`, `missing_module_registration`, `version_drift`, `deprecated_citation`, `broken_state`, `logic_conflict`, `scale_threshold`, `dirty_snapshot`, `unclosed_cnf`, `dfb_escalation`, `trun_signoff_missing`, `apidoc_overwrite`, `changelog_audience_missing`, `home.md_blowout`, `linter_failed`, `milestone_gate_violation`, `raw_source_modification`, `immutability_violation`, `role_boundary_bypass`, `terminal_state_bypass`, `traceability_gap`, `deprecation_propagation_skipped`, `shadow_qa_duplication`, `schema_mismatch`, `linked_node_missing`, `index_entry_missing`, `scenario_gap_present`.275276**Error patterns:** `conflict_class: rule_violation`, `conflict_class: deprecated_citation`, `conflict_class: version_drift`, `conflict_class: decomposition_violation`, `CNF resolution requires BA block`, `DFB escalation 7 days`, `home.md >150 nodes scale_mode:search`, `TRUN sign-off required`, `ephemeral vs durable artifacts`, `pending_ingests`, `open_conflicts`, `open_feedback`, `dirty: true`, `last_compiled older than log.md`, `scenario_gaps: N blocking COMPILE`, `3-bar quality gate failed`, `index_entry_missing on node creation`, `absorb halted mid-batch`, `brownfield init required`.
thapaliyabikendra