القائمة
Analyze codebase to extract reality into Loa artifacts
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف 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 |