Analyze codebase to extract reality into Loa artifacts
You are analyzing an existing codebase to generate evidence-grounded Loa artifacts following the v0.6.0 Enterprise-Grade Managed Scaffolding model.
"The Loa rides through the code, channeling truth into the grimoire."
CODE IS TRUTH → Loa channels CODE → Grimoire reflects REALITY
file:line citationCheck for .loa-version.json. If missing, instruct user to run /mount first. Extract and display framework version.
Verify .claude/checksums.json against actual file hashes. If drift detected:
.claude/overrides/, --force-restore to reset, /update-loa --force-restore to sync--force-restore passedIf no checksums file exists (first ride), skip with warning.
if [[ -f ".claude/commands/ride.md" ]] && [[ -d ".claude/skills/riding-codebase" ]]; then
IS_FRAMEWORK_REPO=true
else
IS_FRAMEWORK_REPO=false
TARGET_REPO="$CURRENT_DIR"
fi
If IS_FRAMEWORK_REPO=true, use AskUserQuestion to select target repo. The Loa rides codebases, not itself.
TRAJECTORY_FILE="grimoires/loa/a2a/trajectory/riding-$(date +%Y%m%d).jsonl"
mkdir -p grimoires/loa/a2a/trajectory
Log preflight completion to trajectory.
If grimoires/loa/reality/.reality-meta.json exists:
generated_at timestamp from the JSONride.staleness_days from .loa.config.yaml (default: 7)--fresh flag NOT passed:
AskUserQuestion: "Ride artifacts are N days old. [R]e-analyze or [S]kip?"--fresh flag: proceed regardless of artifact age.reality-meta.json does not exist: proceed (first ride)Log staleness check to trajectory:
{"phase": 0.6, "action": "staleness_check", "status": "fresh|stale|first_ride", "artifact_age_days": N}
Parse the user's invocation text for enrichment flags. These control whether optional Phases 12-14 run after the standard ride.
Scan the user's invocation for these flags:
| Flag | Variable | Default | Effect |
|---|---|---|---|
--with-gaps | ENRICH_GAPS | false | Enable Phase 12: Gap Tracker |
--with-decisions | ENRICH_DECISIONS | false | Enable Phase 13: Decision Archaeology |
--with-terms | ENRICH_TERMS | false | Enable Phase 14: Terminology Extraction |
--enriched | Sets all three above | false | Enable all enrichment phases |
--enriched is present, set ENRICH_GAPS=true, ENRICH_DECISIONS=true, ENRICH_TERMS=true--with-gaps --with-decisionsfalse — standard ride proceeds unchanged{"phase": "flags", "action": "enrichment_flags_parsed", "status": "complete", "details": {"ENRICH_GAPS": false, "ENRICH_DECISIONS": false, "ENRICH_TERMS": false}}
Read enrichment thresholds from .loa.config.yaml (used by Phases 12-14):
# Gap tracker thresholds
GAP_MAX_OPEN=$(yq eval '.ride.enrichment.gaps.max_open // 200' .loa.config.yaml 2>/dev/null || echo "200")
GAP_WARN_AT=$(yq eval '.ride.enrichment.gaps.warn_at // 150' .loa.config.yaml 2>/dev/null || echo "150")
# Decision archaeology thresholds
DECISION_STALE_MONTHS=$(yq eval '.ride.enrichment.decisions.stale_months // 12' .loa.config.yaml 2>/dev/null || echo "12")
DECISION_EXTRA_PATHS=$(yq eval '.ride.enrichment.decisions.extra_paths // []' .loa.config.yaml 2>/dev/null || echo "[]")
# Terminology thresholds
TERM_MAX_TERMS=$(yq eval '.ride.enrichment.terminology.max_terms // 50' .loa.config.yaml 2>/dev/null || echo "50")
During drift analysis, if .claude/scripts/qmd-context-query.sh exists and qmd_context.enabled is not false:
.claude/scripts/qmd-context-query.sh --query "<module_names>" --scope reality --budget 2000 --format text<attention_budget>
This skill follows the Tool Result Clearing Protocol (.claude/protocols/tool-result-clearing.md).
| Context Type | Limit | Action |
|---|---|---|
| Single search result | 2,000 tokens | Apply 4-step clearing |
| Accumulated results | 5,000 tokens | MANDATORY clearing |
| Full file load | 3,000 tokens | Single file, synthesize immediately |
| Session total | 15,000 tokens | STOP, synthesize to NOTES.md |
file:line refsgrimoires/loa/reality/ or NOTES.md"Probe: N files → M relevant → reality/"Before loading any files, probe the codebase to determine optimal loading strategy.
Use .claude/scripts/context-manager.sh probe "$TARGET_REPO" --json to get file count, line count, estimated tokens, and codebase size category. Fall back to eager loading if probe unavailable.
| Codebase Size | Lines | Strategy |
|---|---|---|
| Small | <10K | Full load — fits in context |
| Medium | 10K-50K | Prioritized — high-relevance first |
| Large | >50K | Excerpts only — too large for full load |
Create grimoires/loa/reality/loading-plan.md with files categorized by should-load decision. For prioritized/excerpts strategies, sort files by relevance score using .claude/scripts/context-manager.sh should-load "$file" --json.
Log probe results to trajectory.
Scan grimoires/loa/context/ for existing documentation files.
Use AskUserQuestion to offer the user a chance to add context files (architecture docs, tribal knowledge, roadmaps) to grimoires/loa/context/ before the interview.
If context files exist, analyze them BEFORE the interview. Generate grimoires/loa/context/context-coverage.md listing:
Use AskUserQuestion for each topic, skipping questions answered by context files:
YOU MUST CREATE grimoires/loa/context/claims-to-verify.md with tables for:
Even if interview is skipped, create this file from existing context.
WRITE TO DISK: Use the Write tool to persist grimoires/loa/context/claims-to-verify.md.
After writing, verify with Glob pattern grimoires/loa/context/claims-to-verify.md — must return 1 match. If missing after Write, retry once. If still missing, log to trajectory:
{"phase": 1, "action": "write_failed", "artifact": "claims-to-verify.md", "status": "error"}
Do NOT render the artifact inline without also writing it to disk.
Clear raw interview data. Summarize captured claims count and top investigation areas.
mkdir -p grimoires/loa/reality
cd "$TARGET_REPO"
Apply the loading strategy from Phase 0.5 to control which files get fully loaded, excerpted, or skipped.
Execute the following extractions, writing results to grimoires/loa/reality/:
| Step | Output File | What to Extract |
|---|---|---|
| 2.2 | structure.md | Directory tree (max depth 4, excluding node_modules/dist/build) |
| 2.3 | api-routes.txt | Route definitions (@Get, @Post, router.*, app.get, etc.) |
| 2.4 | data-models.txt | Models, entities, schemas, CREATE TABLE, interfaces |
| 2.5 | env-vars.txt | process.env.*, os.environ, os.Getenv references |
| 2.6 | tech-debt.txt | TODO, FIXME, HACK, XXX, @deprecated, @ts-ignore |
| 2.7 | test-files.txt | Test files (*.test.ts, *.spec.ts, test.go, test.py) |
See: resources/references/deep-analysis-guide.md for detailed extraction commands and loading strategy helpers.
Clear raw tool outputs. Report counts for routes, entities, env vars, tech debt, tests. Include loading strategy results (files loaded/excerpted/skipped, tokens saved).
Generate grimoires/loa/reality/hygiene-report.md flagging potential issues for HUMAN DECISION:
See: resources/references/deep-analysis-guide.md for the hygiene report template and dead code philosophy.
WRITE TO DISK: Use the Write tool to persist grimoires/loa/reality/hygiene-report.md.
After writing, verify with Glob pattern grimoires/loa/reality/hygiene-report.md — must return 1 match. If missing after Write, retry once. If still missing, log to trajectory:
{"phase": "2b", "action": "write_failed", "artifact": "hygiene-report.md", "status": "error"}
Find all .md, .rst, .txt, .adoc files (excluding node_modules, .git, grimoires/loa). Save to grimoires/loa/legacy/doc-files.txt.
Score existing CLAUDE.md on: length (>50 lines), tech stack mentions, pattern/convention guidance, warnings. Score out of 7; below 5 is insufficient.
Create grimoires/loa/legacy/INVENTORY.md listing all docs with type and key claims.
WRITE TO DISK: Use the Write tool to persist grimoires/loa/legacy/INVENTORY.md.
After writing, verify with Glob pattern grimoires/loa/legacy/INVENTORY.md — must return 1 match. If missing after Write, retry once. If still missing, log to trajectory:
{"phase": 3, "action": "write_failed", "artifact": "INVENTORY.md", "status": "error"}
| Category | Definition | Impact |
|---|---|---|
| Missing | Code exists, no documentation | Medium |
| Stale | Docs exist, code changed | High |
| Hallucinated | Docs claim things code doesn't support | Critical |
| Ghost | Documented feature not in code | Critical |
| Shadow | Code exists, completely undocumented | Medium |
| Aligned | Documentation matches code | Healthy |
Extract claims from legacy docs. For EACH claim, verify against code reality. Determine status: VERIFIED | STALE | HALLUCINATED | MISSING.
Create grimoires/loa/drift-report.md with summary table, drift score, breakdown by type, critical items with verification evidence.
See: resources/references/analysis-checklists.md for the full drift report template.
Log drift analysis to trajectory.
WRITE TO DISK: Use the Write tool to persist grimoires/loa/drift-report.md.
After writing, verify with Glob pattern grimoires/loa/drift-report.md — must return 1 match. If missing after Write, retry once. If still missing, log to trajectory:
{"phase": 4, "action": "write_failed", "artifact": "drift-report.md", "status": "error"}
YOU MUST CREATE grimoires/loa/consistency-report.md.
Analyze naming patterns (entities, functions, files), compute consistency score (1-10), identify conflicts and improvement opportunities. Flag breaking changes without implementing.
See: resources/references/analysis-checklists.md for the consistency report template.
Log to trajectory.
WRITE TO DISK: Use the Write tool to persist grimoires/loa/consistency-report.md.
After writing, verify with Glob pattern grimoires/loa/consistency-report.md — must return 1 match. If missing after Write, retry once. If still missing, log to trajectory:
{"phase": 5, "action": "write_failed", "artifact": "consistency-report.md", "status": "error"}
MANDATORY: Every claim in PRD and SDD MUST use grounding markers:
| Marker | When to Use |
|---|---|
[GROUNDED] | Direct code evidence with file:line citation |
[INFERRED] | Logical deduction from multiple sources |
[ASSUMPTION] | No direct evidence — needs validation |
Extended Markers (available when enrichment phases run):
| Marker | When to Use | Example |
|---|---|---|
[CLAIMED: source] | Single-source evidence with attribution | [CLAIMED: ADR-003 — Dynamic over Privy] |
[DISPUTED: A vs B] | Conflicting signals between sources | [DISPUTED: README says Redis, code uses in-memory] |
[UNKNOWN: GAP-NNN] | Linked to gap tracker entry | [UNKNOWN: GAP-007 — auth session TTL] |
These extended markers complement (not replace) the standard markers above and the BUTTERFREEZONE provenance tags (CODE-FACTUAL, DERIVED, OPERATIONAL). Use them in reality files (grimoires/loa/reality/*.md) and the gap tracker when enrichment phases produce evidence that warrants richer attribution.
Create grimoires/loa/prd.md with evidence-grounded user types, features, and requirements. Include Source of Truth notice and Document Metadata.
Create grimoires/loa/sdd.md with verified tech stack, module structure, data model, and API surface. All with grounding markers and evidence.
Append to BOTH PRD and SDD: counts and percentages of GROUNDED/INFERRED/ASSUMPTION claims, plus assumptions requiring validation.
Quality Target: >80% GROUNDED, <10% ASSUMPTION
See: resources/references/output-formats.md for PRD, SDD, and grounding summary templates.
Log to trajectory.
WRITE TO DISK: Use the Write tool to persist BOTH artifacts:
| File | Path |
|---|---|
| PRD | grimoires/loa/prd.md |
| SDD | grimoires/loa/sdd.md |
After writing each, verify with Glob — must return 1 match per file. If either missing after Write, retry once. If still missing, log to trajectory:
{"phase": 6, "action": "write_failed", "artifact": "prd.md|sdd.md", "status": "error"}
Generate token-optimized reality files for the /reality command in grimoires/loa/reality/:
| File | Purpose | Token Budget |
|---|---|---|
index.md | Hub/routing file | < 500 |
api-surface.md | Public function signatures, API endpoints | < 2000 |
types.md | Type/interface definitions grouped by domain | < 2000 |
interfaces.md | External integration patterns, webhooks | < 1000 |
structure.md | Annotated directory tree, module responsibilities | < 1000 |
entry-points.md | Main files, CLI commands, env requirements | < 500 |
architecture-overview.md | System component diagram, data flows, tech stack, entry points | < 1500 |
Also generate .reality-meta.json with token counts and staleness threshold.
Total budget: < 8500 tokens across all files (7000 base + 1500 architecture-overview).
See: resources/references/output-formats.md for all reality file templates.
Log to trajectory.
WRITE TO DISK: Use the Write tool to persist ALL reality files:
| File | Path |
|---|---|
| Index | grimoires/loa/reality/index.md |
| API Surface | grimoires/loa/reality/api-surface.md |
| Types | grimoires/loa/reality/types.md |
| Interfaces | grimoires/loa/reality/interfaces.md |
| Structure | grimoires/loa/reality/structure.md |
| Entry Points | grimoires/loa/reality/entry-points.md |
| Architecture Overview | grimoires/loa/reality/architecture-overview.md |
| Reality Meta | grimoires/loa/reality/.reality-meta.json |
After writing each file, verify with Glob — each must return 1 match. Log any failures to trajectory:
{"phase": 6.5, "action": "write_failed", "artifact": "{filename}", "status": "error"}
Generate grimoires/loa/governance-report.md:
| Artifact | Check for |
|---|---|
| CHANGELOG.md | Version history |
| CONTRIBUTING.md | Contribution process |
| SECURITY.md | Security disclosure policy |
| CODEOWNERS | Required reviewers |
| Semver tags | Release versioning |
WRITE TO DISK: Use the Write tool to persist grimoires/loa/governance-report.md.
After writing, verify with Glob pattern grimoires/loa/governance-report.md — must return 1 match. If missing after Write, retry once. If still missing, log to trajectory:
{"phase": 7, "action": "write_failed", "artifact": "governance-report.md", "status": "error"}
For each file in legacy/doc-files.txt, prepend a deprecation notice pointing to grimoires/loa/prd.md and grimoires/loa/sdd.md as the new source of truth, with reference to grimoires/loa/drift-report.md.
Checkpoint coverage note: Phases 2 (extraction), 3 (
doc-files.txt), and 8 (deprecation) produce intermediate or modified artifacts not covered by write checkpoints. Phase 2 extractions are working data consumed immediately by later phases. Phase 3'sINVENTORY.mdis covered by CP-3;doc-files.txtis an intermediate file. Phase 8 modifies existing files rather than creating new ones, so existence checks do not apply.
YOU MUST CREATE grimoires/loa/trajectory-audit.md.
Count grounding markers ([GROUNDED], [INFERRED], [ASSUMPTION]) in both PRD and SDD.
Include: execution summary table (all phases with status/output/findings), grounding analysis for PRD and SDD, claims requiring validation, hallucination checklist, reasoning quality score (1-10).
See: resources/references/analysis-checklists.md for the full self-audit template.
IMPORTANT: If trajectory file is empty at Phase 9, flag as failure.
Log to trajectory.
WRITE TO DISK: Use the Write tool to persist grimoires/loa/trajectory-audit.md.
After writing, verify with Glob pattern grimoires/loa/trajectory-audit.md — must return 1 match. If missing after Write, retry once. If still missing, log to trajectory:
{"phase": 9, "action": "write_failed", "artifact": "trajectory-audit.md", "status": "error"}
Before handoff, verify ALL expected artifacts exist on disk using Glob.
Full Mode Checklist:
| # | Artifact | Path |
|---|---|---|
| 1 | Claims to Verify | grimoires/loa/context/claims-to-verify.md |
| 2 | Hygiene Report | grimoires/loa/reality/hygiene-report.md |
| 3 | Drift Report | grimoires/loa/drift-report.md |
| 4 | Consistency Report | grimoires/loa/consistency-report.md |
| 5 | PRD | grimoires/loa/prd.md |
| 6 | SDD | grimoires/loa/sdd.md |
| 7 | Reality Index | grimoires/loa/reality/index.md |
| 8 | Governance Report | grimoires/loa/governance-report.md |
| 9 | Trajectory Audit | grimoires/loa/trajectory-audit.md |
| 10 | Reality Meta | grimoires/loa/reality/.reality-meta.json |
| 11 | Legacy Inventory | grimoires/loa/legacy/INVENTORY.md |
Enrichment Artifacts (check only when corresponding flag was set):
| # | Artifact | Path | Condition |
|---|---|---|---|
| 12 | Gap Tracker | grimoires/loa/gaps.md | ENRICH_GAPS == true |
| 13 | Decision Archaeology | grimoires/loa/reality/decisions.md | ENRICH_DECISIONS == true |
| 14 | Domain Terminology | grimoires/loa/reality/terminology.md | ENRICH_TERMS == true |
Procedure:
Glob to verify existenceThe ride MUST NOT complete with 0/N artifacts verified. If critical artifacts (drift-report, consistency-report, governance-report, trajectory-audit, hygiene-report) are missing, flag as ride failure.
Add session continuity entry and ride results (routes documented, entities, tech debt, drift score, governance gaps).
The Loa Has Ridden
Artifact Verification: X/Y files persisted
Grimoire Artifacts Created:
- grimoires/loa/prd.md (Product truth)
- grimoires/loa/sdd.md (System truth)
- grimoires/loa/drift-report.md (Three-way analysis)
- grimoires/loa/consistency-report.md (Pattern analysis)
- grimoires/loa/governance-report.md (Process gaps)
- grimoires/loa/reality/* (Raw extractions + token-optimized files)
- grimoires/loa/trajectory-audit.md (Self-audit)
Enrichment Outputs (if enabled):
- grimoires/loa/gaps.md (Gap tracker — if --with-gaps)
- grimoires/loa/reality/decisions.md (Decision archaeology — if --with-decisions)
- grimoires/loa/reality/terminology.md (Domain terminology — if --with-terms)
Next Steps:
1. Review drift-report.md for critical issues
2. Address governance gaps
3. /translate-ride for executive communications
4. Schedule stakeholder PRD review
5. Run /implement for high-priority drift
6. Review gaps.md and resolve open gaps (if enrichment ran)
--ground-truth only)This phase runs only when the --ground-truth flag is passed. It produces a token-efficient, deterministically-verified codebase summary for agent consumption.
When --ground-truth --non-interactive is passed, phases 1 (Interactive Context Discovery), 3 (Legacy Doc Inventory), and 8 (Legacy Deprecation) are skipped — only extraction, analysis, and GT generation run.
Read the reality/ files generated in Phase 2 and Phase 6.5. These contain the code truth that GT will summarize.
Generate hub-and-spoke Ground Truth files:
| File | Purpose | Token Budget |
|---|---|---|
index.md | Hub document with navigation and quick stats | ~500 |
api-surface.md | Public APIs, endpoints, exports | ~2000 |
architecture.md | System topology, data flow, dependencies | ~2000 |
contracts.md | Inter-system contracts, types, interfaces | ~2000 |
behaviors.md | Runtime behaviors, triggers, thresholds | ~2000 |
Every factual claim MUST cite a source file and line range (file:line). The grounding ratio must be >= 0.95.
Invoke ground-truth-gen.sh for mechanical operations:
.claude/scripts/ground-truth-gen.sh \
--reality-dir grimoires/loa/reality/ \
--output-dir grimoires/loa/ground-truth/ \
--max-tokens-per-section 2000 \
--mode checksums
This produces checksums.json with SHA-256 hashes of all referenced source files.
.claude/scripts/ground-truth-gen.sh \
--output-dir grimoires/loa/ground-truth/ \
--max-tokens-per-section 2000 \
--mode validate
If any section exceeds its token budget, trim content (prioritize most-referenced APIs/components) and re-validate.
{"phase": 11, "action": "ground_truth_generation", "status": "complete", "details": {"files": 5, "total_tokens": N, "checksums_count": N, "within_budget": true}}
ENRICH_GAPS only)Skip condition: If ENRICH_GAPS == false, skip this entire phase. Log skip to trajectory:
{"phase": 12, "action": "gap_tracker", "status": "skipped", "details": {"reason": "ENRICH_GAPS not set"}}
Read grimoires/loa/gaps.md if it exists. Extract the highest GAP-NNN numeric ID to determine the next available ID. If file doesn't exist, start at GAP-001. Generate a session-scoped hash to prevent concurrent ID collisions.
# Extract highest gap ID (handles both GAP-NNN and GAP-NNN-HASH formats)
NEXT_GAP_ID=1
if [[ -f grimoires/loa/gaps.md ]]; then
HIGHEST=$(grep -oP 'GAP-\K[0-9]+' grimoires/loa/gaps.md | sort -n | tail -1)
NEXT_GAP_ID=$((HIGHEST + 1))
fi
# Generate 4-character session hash for concurrent safety
SESSION_HASH=$(date +%s%N | sha256sum | head -c 4)
Gap ID format: GAP-{NNN}-{SESSION_HASH} (e.g., GAP-005-a3f2). The session hash ensures that concurrent /ride --with-gaps sessions produce unique IDs even if they read the same highest NNN value before either writes. Existing GAP-NNN entries (without hash) remain valid — the numeric extraction regex accepts both formats.
Scan the following ride artifacts for unknowns, unresolved items, and missing context:
| Source | What to Look For |
|---|---|
grimoires/loa/context/claims-to-verify.md | Claims with status UNVERIFIED or MISSING |
grimoires/loa/drift-report.md | Drift items marked HALLUCINATED or GHOST |
grimoires/loa/governance-report.md | Missing governance artifacts |
| Interview responses (Phase 1) | Questions the user couldn't answer |
grimoires/loa/reality/hygiene-report.md | Unexplained code patterns |
For each identified gap, assign:
Fact | Data | Interview | Context | TechnicalP0 (blocks agent work) | P1 (degrades agent quality) | P2 (nice to know)Write grimoires/loa/gaps.md with the following schema. If the file already exists, append new gaps to the ## Open Gaps section — never overwrite or remove existing entries.
# Gap Tracker
> Auto-generated by /ride --with-gaps. Gaps are NEVER auto-resolved — only humans close them.
> Generated: YYYY-MM-DD
## Open Gaps
### GAP-NNN-HASH: [Short description]
- **Type**: Fact | Data | Interview | Context | Technical
- **Priority**: P0 | P1 | P2
- **Source**: /ride Phase N, [artifact or file:line]
- **Context**: Why this matters for agent work
- **Status**: OPEN
- **Opened**: YYYY-MM-DD
- **Resolution**: _pending human input_
## Resolved Gaps
_Gaps are moved here by humans only. Agents MUST NOT modify this section._
Check gap counts against configured thresholds:
IF total_open_gaps >= GAP_MAX_OPEN:
→ Log ERROR to trajectory and NOTES.md:
"Gap tracker has N open gaps (max: GAP_MAX_OPEN). Review and resolve gaps before adding more."
→ Still write the file, but add warning banner
ELSE IF total_open_gaps >= GAP_WARN_AT:
→ Log WARNING to trajectory:
"Gap tracker approaching limit: N/GAP_MAX_OPEN open gaps"
WRITE TO DISK: Use the Write tool to persist grimoires/loa/gaps.md.
After writing, verify with Glob pattern grimoires/loa/gaps.md — must return 1 match. If missing after Write, retry once. If still missing, log to trajectory:
{"phase": 12, "action": "write_failed", "artifact": "gaps.md", "status": "error"}
| Rule | Description |
|---|---|
| Agents MAY create gaps | Append to Open Gaps section with next monotonic ID + session hash |
| Agents MUST NOT resolve gaps | Only humans move gaps to Resolved section |
| IDs are session-scoped | Format: GAP-{NNN}-{HASH}. NNN is monotonically increasing; HASH is per-session for concurrent safety |
| Backward compatible | Existing GAP-NNN entries (no hash) remain valid and parseable |
| Append-only for new gaps | Subsequent /ride runs append, never overwrite existing entries |
| Check before assuming | Agents SHOULD read gap tracker before making assumptions about unknown context |
Log phase completion to trajectory:
{"phase": 12, "action": "gap_tracker", "status": "complete", "details": {"new_gaps": N, "total_open": N, "highest_id": "GAP-NNN-HASH", "session_hash": "HASH", "threshold_status": "ok|warning|exceeded"}}
ENRICH_DECISIONS only)Skip condition: If ENRICH_DECISIONS == false, skip this entire phase. Log skip to trajectory:
{"phase": 13, "action": "decision_archaeology", "status": "skipped", "details": {"reason": "ENRICH_DECISIONS not set"}}
Search for architectural decision records in these locations (in order):
| Priority | Path Pattern | Convention |
|---|---|---|
| 1 | docs/decisions/ or docs/adr/ | Common patterns |
| 2 | adr/ | Root-level ADR directory |
| 3 | knowledge/decisions/ | Hivemind pattern |
| 4 | docs/architecture/decisions/ | Nested architecture pattern |
| 5 | .adr-dir file contents | adr-tools convention (file contains custom path) |
Also check DECISION_EXTRA_PATHS from config for additional search locations.
Log which directories were found:
{"phase": 13.1, "action": "adr_detection", "dirs_checked": 5, "dirs_found": ["docs/adr/"], "total_adrs": N}
For each .md file found in ADR directories, extract:
| Field | Detection Strategy |
|---|---|
| Title | First # heading or filename |
| Status | Line matching Status: or ## Status section (Accepted, Deprecated, Superseded, Proposed) |
| Date | Line matching Date:, Decided:, or parsed from filename (NNNN-NN-NN pattern) |
| Decision | First paragraph after ## Decision, ## Context and Decision, or ## Decision Outcome (MADR) heading |
| Rejected alternatives | Content under ## Options Considered, ## Alternatives, ## Rejected, ## Considered Options (MADR), or ## Pros and Cons of the Options (MADR) |
| Consequences | Content under ## Consequences, ## Impact, or ## Positive/Negative Consequences (MADR) |
| Reversal conditions | Sentences containing "revisit when", "reconsider if", "reverse when", "sunset" |
Heading matching: Case-insensitive. Accept both ## and ### heading levels. MADR variants (marked above) follow the Markdown Architectural Decision Records standard.
For each ADR with a detected date:
age_months = (current_date - adr_date) / 30
IF age_months > DECISION_STALE_MONTHS:
→ Mark as STALE with warning: "N months old, may not reflect current decisions"
Write grimoires/loa/reality/decisions.md:
# Decision Archaeology
> Extracted from N ADR files across M directories.
> Decisions are claims — verify with HITL before treating as constraints.
> Generated: YYYY-MM-DD
## Active Decisions
### [ADR Title]
- **Status**: [Status] ([Date])
- **File**: [relative/path/to/adr.md]
- **Decision**: [Summary of decision]
- **Rejected**: [Alternatives that were NOT chosen]
- **Constraints for agents**: [What agents should NOT do based on this decision]
- **Reversal condition**: [If present — when to reconsider]
## Stale Decisions (>DECISION_STALE_MONTHS months, no reconfirmation)
### [ADR Title]
- **Status**: [Status] ([Date]) — ⚠️ N months old
- **File**: [relative/path/to/adr.md]
- **Staleness note**: May not reflect current architecture decisions. Recommend HITL reconfirmation.
If no ADR directories or files are found:
GAP-NNN-HASH: No ADR/decision records found
Type: Context
Priority: P1
Source: /ride Phase 13, decision archaeology scan
Context: Project has no documented architectural decisions. Future agents will lack trade-off context.
WRITE TO DISK: Use the Write tool to persist grimoires/loa/reality/decisions.md.
After writing, verify with Glob pattern grimoires/loa/reality/decisions.md — must return 1 match. If missing after Write, retry once. If still missing, log to trajectory:
{"phase": 13, "action": "write_failed", "artifact": "decisions.md", "status": "error"}
Log phase completion:
{"phase": 13, "action": "decision_archaeology", "status": "complete", "details": {"adr_dirs_found": N, "adrs_parsed": N, "active": N, "stale": N, "output": "grimoires/loa/reality/decisions.md"}}
ENRICH_TERMS only)Skip condition: If ENRICH_TERMS == false, skip this entire phase. Log skip to trajectory:
{"phase": 14, "action": "terminology_extraction", "status": "skipped", "details": {"reason": "ENRICH_TERMS not set"}}
Scan source code for domain-specific vocabulary from these categories (in priority order):
If tsconfig.json exists at the project root, include TypeScript-enhanced patterns (marked with † below). Otherwise, use base patterns only.
| Category | Detection Pattern | Example |
|---|---|---|
| Type names & enums | type\s+\w+, enum\s+\w+, interface\s+\w+ | type FinnNFT, enum PoolStatus |
| Type names (TS-enhanced †) | type\s+\w+< (generics), as const assertions, satisfies\s+\w+, .d.ts file exports | type Pool<T>, const ROLES = {...} as const |
| Database models | @Entity, model\s+\w+, CREATE TABLE, schema definitions | model CreditBalance |
| Constants | const\s+[A-Z_]+, exported configuration keys | MAX_RETRY_COUNT |
| Component names | Domain-prefixed components, module names | HounfourRouter, BridgebuilderReview |
| Definitional comments | Comments containing "i.e.", "a.k.a.", "means", "refers to", "defined as" | // finnNFT refers to the governance token |
For each term found:
file:line)TERM_MAX_TERMS (default: 50)Write grimoires/loa/reality/terminology.md:
# Domain Terminology
> Extracted from source code. N terms identified.
> Generated: YYYY-MM-DD
## [Domain Group 1]
| Term | Source | Context |
|------|--------|---------|
| `TermName` | path/to/file.ts:NN | Brief definition or usage context |
## [Domain Group 2]
| Term | Source | Context |
|------|--------|---------|
| `TermName` | path/to/file.ts:NN | Brief definition or usage context |
WRITE TO DISK: Use the Write tool to persist grimoires/loa/reality/terminology.md.
After writing, verify with Glob pattern grimoires/loa/reality/terminology.md — must return 1 match. If missing after Write, retry once. If still missing, log to trajectory:
{"phase": 14, "action": "write_failed", "artifact": "terminology.md", "status": "error"}
Log phase completion:
{"phase": 14, "action": "terminology_extraction", "status": "complete", "details": {"terms_extracted": N, "domains": N, "output": "grimoires/loa/reality/terminology.md"}}
If code behavior is ambiguous:
file:lineAskUserQuestionNOTES.mdNever assume. Always ground in evidence.
YOU MUST LOG EACH PHASE to grimoires/loa/a2a/trajectory/riding-{date}.jsonl.
Each phase appends a JSON line:
{"timestamp": "ISO8601", "agent": "riding-codebase", "phase": N, "action": "phase_name", "status": "complete", "details": {...}}
| Phase | Action | Key Details Fields |
|---|---|---|
| 0 | preflight | loa_version |
| 0.5 | codebase_probe | strategy, total_files, total_lines, estimated_tokens |
| 0.6 | staleness_check | status, artifact_age_days |
| 1 | claims_generated | claim_count, output |
| 2 | code_extraction | routes, entities, env_vars |
| 2b | hygiene_audit | items_flagged |
| 3 | legacy_inventory | docs_found |
| 4 | drift_analysis | drift_score, ghosts, shadows, stale |
| 5 | consistency_analysis | score, output |
| 6 | artifact_generation | prd_claims, sdd_claims, grounded_pct |
| 6.5 | reality_generation | files, total_tokens, within_budget |
| 7 | governance_audit | gaps |
| 8 | legacy_deprecation | files_marked |
| 9 | self_audit | quality_score, assumptions, output |
| 10 | handoff | total_duration_minutes |
| 11 | ground_truth_generation | files, total_tokens, checksums_count, within_budget |
| 12 | gap_tracker | new_gaps, total_open, highest_id, threshold_status |
| 13 | decision_archaeology | adr_dirs_found, adrs_parsed, active, stale, output |
| 14 | terminology_extraction | terms_extracted, domains, output |