القائمة
Analyze codebase to extract reality into Loa artifacts
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Single-pass network health observation. Checks API liveness, namespace freshness, drift, computes Network Health Score.
Deep investigation of a single construct. Identity-reality drift, maintenance pattern, composition analysis.
Single-pass network health observation. Checks API liveness, namespace freshness, drift, computes Network Health Score.
Autonomous observation loop. Time-boxed cycles with ratcheting health score, commits findings to grimoires.
Synthesize observations into a readable network health report. Aggregates patterns and trends from observation cycles.
Single-pass coherence sense of an ARBITRARY estate (a registry/state pair). Resolves the read-command from operator-local estate-config, shells the estate's own doctor read-only, emits exactly the STATUS|SIGNAL|MISMATCH tile. Sense-only — never mutates the estate.
| name | ride |
| description | Analyze codebase to extract reality into Loa artifacts |
| role | planning |
| context | fork |
| allowed-tools | Read, Grep, Glob, Write, Bash(git *) |
| capabilities | {"schema_version":1,"read_files":true,"search_code":true,"write_files":true,"execute_commands":true,"web_access":false,"user_interaction":false,"agent_spawn":false,"task_management":false} |
| cost-profile | heavy |
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 |
--with-simplicity | ENRICH_SIMPLICITY | false | Enable Phase 15: Over-Engineering Audit + shortcut ledger |
--enriched | Sets all four above | false | Enable all enrichment phases |
--enriched is present, set ENRICH_GAPS=true, ENRICH_DECISIONS=true, ENRICH_TERMS=true, ENRICH_SIMPLICITY=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"}}
ENRICH_SIMPLICITY only)Skip condition: If ENRICH_SIMPLICITY == false, skip this phase. Log skip to trajectory:
{"phase": 15, "action": "simplicity_audit", "status": "skipped", "details": {"reason": "ENRICH_SIMPLICITY not set"}}
The complexity-only counterpart to a security audit: a ranked, whole-repo
over-engineering pass plus a dedicated loa:shortcut: debt ledger. Reports
only, applies no fixes.
Apply the reviewing-code over-engineering taxonomy (delete / stdlib /
native / yagni / shrink) tree-wide instead of to a diff. Hunt:
dependencies the stdlib or platform already ships, single-implementation
interfaces, factories with one product, wrappers that only delegate, dead
flags/config, hand-rolled stdlib. One line per finding, ranked biggest-cut
first: <tag>: <what to cut>. <replacement>. [path:line]. End with
net: -<N> lines, -<M> deps possible. Nothing to cut: Lean already. Ship.
loa:shortcut: debt ledgerHarvest deliberate-simplification markers (distinct from the generic TODO/FIXME tech-debt scan in the standard ride):
grep -rnE '(#|//|--) ?loa:shortcut:' . \
--exclude-dir={.git,node_modules,dist,build} \
> grimoires/loa/reality/shortcut-ledger.raw 2>/dev/null || true
One row per marker, grouped by file, parsing the loa:shortcut: <ceiling>, <upgrade> convention:
<file>:<line> - <what was simplified>. ceiling: <limit>. upgrade: <trigger>.
Any marker naming a ceiling with NO upgrade trigger gets a no-trigger tag,
those rot silently. End with <N> markers, <M> no-trigger. None found:
No loa:shortcut: debt. Clean ledger.
Write both sections to grimoires/loa/reality/over-engineering.md (ranked
findings, then ledger). Log completion:
{"phase": 15, "action": "simplicity_audit", "status": "complete", "details": {"findings": N, "net_lines": -N, "markers": N, "no_trigger": N, "output": "grimoires/loa/reality/over-engineering.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 |