Menú
Analyze codebase to extract reality into Loa artifacts
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
Bridgebuilder — Autonomous PR Review
Triage a bug report through structured phases and create micro-sprint
Launch PRD discovery with codebase grounding and context ingestion
Execute sprint tasks with production-quality code and tests
Validate sprint implementation against acceptance criteria
Security and quality audit of application codebase
| 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<context_discipline>
Follow .claude/protocols/tool-result-clearing.md. Thresholds: single result >2K tokens /
accumulated >5K / full file >3K / session total >15K → extract findings (≤10 files, ≤20 words
each, with file:line) to grimoires/loa/NOTES.md, then reason from the synthesis, not raw dumps.
Session start: read NOTES.md "Session Continuity". Session end / pre-compaction: update it
(decisions → Decision Log, discovered issues → Technical Debt).
</context_discipline>
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.
See: resources/references/enrichment-phases.md#phase-11-ground-truth-generation for the full procedure.
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"}}
See: resources/references/enrichment-phases.md#phase-12-gap-tracker-generation for the full procedure.
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"}}
See: resources/references/enrichment-phases.md#phase-13-decision-archaeology for the full procedure.
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"}}
See: resources/references/enrichment-phases.md#phase-14-domain-terminology-extraction for the full procedure.
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"}}
See: resources/references/enrichment-phases.md#phase-15-over-engineering-audit--shortcut-ledger for the full procedure.
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 |