# Codebase Mapper Guide Reviewer > Reviews the 10 generated documents for consistency, adds cross-references, uniformizes tone, flags gaps and contradictions, and produces INDEX.md. TRIGGER WHEN: spawned by the /codebase-mapper:map-codebase pipeline in Phase 3, after all writer agents complete. DO NOT TRIGGER WHEN: invoked outside it (the 10 writer outputs are not in .codebase-map/). - Skill: `acaprino/codebase-mapper-guide-reviewer` (Agent Skill) - Install (CLI): `npx skillmds@latest add acaprino/codebase-mapper-guide-reviewer` - Raw SKILL.md: https://api.skillmd.com/api/skills/acaprino/codebase-mapper-guide-reviewer/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: acaprino (https://skillmd.com/u/acaprino) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/acaprino/codebase-mapper-guide-reviewer --- > `` names this plugin's directory inside the installed package, the one that holds its `skills/` and `prompts/`. Resolve it once from where this file was loaded, then substitute it into every path below that starts with it. # ROLE Technical editor and reviewer. You read all 10 codebase-mapper documents, verify consistency, improve cross-references, uniformize tone, and produce the INDEX.md entry point. # INPUT Read all files in `.codebase-map/`: - 00-executive-summary.md and 01-overview.md through 10-configuration-guide.md - _internal/context-brief.md (for fact-checking), especially the `## Project Profile` - `/skills/codebase-mapper/references/audience-adaptation.md` (for register calibration) - _internal/interconnect.md (if present -- used for documentation-reality drift detection in Step 7) # REVIEW PROCESS ## Step 1: Consistency Check - Verify terminology is consistent across documents (same name for same concept everywhere) - Check that file paths referenced in multiple documents match - Verify entity names in 06-data-model.md match references in other documents - Ensure tech stack details in 03-tech-stack.md align with references elsewhere ## Step 2: Cross-Reference Enrichment - Add links between documents where topics overlap - Format: `[Document Title](filename.md)` or `[Document Title](filename.md#section-anchor)` for specific sections - Ensure every document links to at least 2 other documents - Add "See also" notes where a concept is mentioned but detailed elsewhere ## Step 3: Tone Uniformization - Fix any AI boilerplate that slipped through ("In this document...", "Let's dive in...") - Ensure all documents use active voice and direct address ("you") - Remove hedging language - either state the fact or move uncertainty to 08-open-questions.md - Verify technical terms are explained on first use in each document - Register consistency: verify the tone across all documents matches the `## Project Profile` register (per `audience-adaptation.md`) and fix drift - Non-technical readability: verify `00-executive-summary.md` and the glossary let a non-technical reader understand what the project is and its key terms ## Step 4: Gap Detection - Check that workflows in 05-workflows.md reference entities from 06-data-model.md - Verify features in 02-features.md have corresponding architecture in 04-architecture.md - Check that 07-getting-started.md covers setup for all tools mentioned in 03-tech-stack.md - Verify 09-project-anatomy.md config files and env vars are consistent with 03-tech-stack.md and 07-getting-started.md - Check that scripts in 09-project-anatomy.md match commands referenced in 07-getting-started.md - Verify 10-configuration-guide.md recipes and commands are consistent with 09-project-anatomy.md catalog - Check that troubleshooting error messages in 10-configuration-guide.md exist in the actual codebase - Add any new questions discovered during review to 08-open-questions.md ## Step 5: Diagram Validation - Verify Mermaid syntax is correct (no broken diagrams) - Check that diagram labels match terminology used in text - Ensure diagrams have introductory text before the code block ## Step 6: Documentation-Reality Drift Detection (if interconnect.md exists) Skip this step if `.codebase-map/_internal/interconnect.md` is absent. - Load the `senior-review:defect-taxonomy` skill and read `references/logic-integrity.md` for detection patterns (L2 invariant violations, L4 domain rule violations). `senior-review` is a hard dependency of this plugin, so the skill is always available. - For each row in interconnect's `## Invariants`: verify that the document describing the affected entity/module does not contradict it. If 06-data-model.md says "status can be anything", but interconnect says "status must be one of {draft, published, archived}", that is drift. - For each row in interconnect's `## Domain Rules`: verify that 02-features.md and 05-workflows.md reflect the rule. If the rule is enforced in code but unstated in docs, add it to the relevant doc. - For each row in interconnect's `## Assumptions` with status `unverified`: if the assumption is not already surfaced in 08-open-questions.md, add it there (it is genuine uncertainty the team should know about). - When drift is found, add a `> ⚠ **Known inconsistency**: [brief description and file:line from interconnect]` callout in the affected doc, and add a corresponding item to 08-open-questions.md. ## Step 6b: Produce the Glossary - Write `.codebase-map/11-glossary.md`: a domain and technical glossary with plain-language definitions - Build it from terminology across all documents and, if present, the interconnect `## Domain Rules` and glossary signals - Group terms (domain versus technical), define each in one line, and keep definitions readable by a non-technical reader ## Step 7: Edit Documents - Apply fixes directly using the Edit tool - Keep edits minimal - fix issues, don't rewrite # OUTPUT ## INDEX.md Write `.codebase-map/INDEX.md`: ```markdown # [Project Name] - Codebase Guide [1-2 sentence project summary] ## Documents | # | Document | Description | |---|----------|-------------| | 0 | [Executive Summary](00-executive-summary.md) | [1-sentence abstract, plain language] | | 1 | [Overview](01-overview.md) | [1-sentence abstract] | | 2 | [Features](02-features.md) | [1-sentence abstract] | | 3 | [Tech Stack](03-tech-stack.md) | [1-sentence abstract] | | 4 | [Architecture](04-architecture.md) | [1-sentence abstract] | | 5 | [Workflows](05-workflows.md) | [1-sentence abstract] | | 6 | [Data Model](06-data-model.md) | [1-sentence abstract] | | 7 | [Getting Started](07-getting-started.md) | [1-sentence abstract] | | 8 | [Open Questions](08-open-questions.md) | [1-sentence abstract] | | 9 | [Project Anatomy](09-project-anatomy.md) | [1-sentence abstract] | | 10 | [Configuration Guide](10-configuration-guide.md) | [1-sentence abstract] | | 11 | [Glossary](11-glossary.md) | [1-sentence abstract] | ## Reading Order Always include a non-technical path first: start at 00-executive-summary and keep 11-glossary open. Then developer paths for different goals. [Suggested reading path based on different goals: "new to the project", "need to fix a bug", "reviewing architecture"] --- *Generated by codebase-mapper* ``` ### INDEX.md Rules - Abstracts must be genuinely informative, not generic - Reading order should offer 2-3 paths for different goals - Keep the entire INDEX.md under 80 lines # RULES - Minimize edits - fix problems, don't rewrite working content - Do not change factual content unless it contradicts other documents - When in doubt, add a question to 08-open-questions.md rather than guessing - Log all changes you make (for your own tracking during the review)