Use this skill when the user explicitly asks to map, document, or onboard into an existing codebase. Trigger for prompts like "map this codebase", "document this architecture", "onboard me to this repo", or "create codebase docs". Do not trigger for routine feature implementation, bug fixes, or narrow code edits unless the user asks for repository-level discovery.
Produces seven populated documents in docs/codebase/ covering everything needed to work effectively on the project. Only document what is verifiable from files or terminal output — never infer or assume.
Before finishing, all of the following must be true:
docs/codebase/: STACK.md, STRUCTURE.md, ARCHITECTURE.md, CONVENTIONS.md, INTEGRATIONS.md, TESTING.md, CONCERNS.md.[TODO]; intent-dependent decisions are marked [ASK USER].[ASK USER] questions and intent-vs-reality divergences.Copy and track this checklist:
- [ ] Phase 1: Run scan, read intent documents
- [ ] Phase 2: Investigate each documentation area
- [ ] Phase 3: Populate all seven docs in docs/codebase/
- [ ] Phase 4: Validate docs, present findings, resolve all [ASK USER] items
If the user supplies a focus area (for example: "architecture only" or "testing and concerns"):
[TODO].Run the scan script from the target project root:
python3 "$SKILL_ROOT/scripts/scan.py" --output docs/codebase/.codebase-scan.txt
Where $SKILL_ROOT is the absolute path to the skill folder. Works on Windows, macOS, and Linux.
Quick start: If you have the path inline:
python3 /absolute/path/to/skills/acquire-codebase-knowledge/scripts/scan.py --output docs/codebase/.codebase-scan.txt
Search for PRD, TRD, README, ROADMAP, SPEC, DESIGN files and read them.
Summarise the stated project intent before reading any source code.
Use the scan output to answer questions for each of the seven templates. Load references/inquiry-checkpoints.md for the full per-template question list.
If the stack is ambiguous (multiple manifest files, unfamiliar file types, no package.json), load references/stack-detection.md.
Copy each template from assets/templates/ into docs/codebase/. Fill in this order:
Use [TODO] for anything that cannot be determined from code. Use [ASK USER] where the right answer requires team intent.
Run this mandatory validation loop before finalizing:
references/inquiry-checkpoints.md.Then present a summary of all seven documents, list every [ASK USER] item as a numbered question, and highlight any Intent vs. Reality divergences from Phase 1.
Validation pass criteria:
[TODO] rather than assumptions.[ASK USER].Monorepos: Root package.json may have no source — check for workspaces, packages/, or apps/ directories. Each workspace may have independent dependencies and conventions. Map each sub-package separately.
Outdated README: README often describes intended architecture, not the current one. Cross-reference with actual file structure before treating any README claim as fact.
TypeScript path aliases: tsconfig.json paths config means imports like @/foo don't map directly to the filesystem. Map aliases to real paths before documenting structure.
Generated/compiled output: Never document patterns from dist/, build/, generated/, .next/, out/, or __pycache__/. These are artefacts — document source conventions only.
.env.example reveals required config: Secrets are never committed. Read .env.example, .env.template, or .env.sample to discover required environment variables.
devDependencies ≠ production stack: Only dependencies (or equivalent, e.g. [tool.poetry.dependencies]) runs in production. Document linters, formatters, and test frameworks separately as dev tooling.
Test TODOs ≠ production debt: TODOs inside test/, tests/, __tests__/, or spec/ are coverage gaps, not production technical debt. Separate them in CONCERNS.md.
High-churn files = fragile areas: Files appearing most in recent git history have the highest modification rate and likely hidden complexity. Always note them in CONCERNS.md.
| ❌ Don't | ✅ Do instead |
|---|---|
| "Uses Clean Architecture with Domain/Data layers." (when no such directories exist) | State only what directory structure actually shows. |
"This is a Next.js project." (without checking package.json) | Check dependencies first. State what's actually there. |
Guess the database from a variable name like dbUrl | Check manifest for pg, mysql2, mongoose, prisma, etc. |
Document dist/ or build/ naming patterns as conventions | Source files only. |
The scan.py script now produce the following sections in addition to the original output:
Use these sections during Phase 2 to inform investigation questions and identify tool-specific patterns.
| Asset | When to load |
|---|---|
scripts/scan.py | Phase 1 — run first, before reading any code (Python 3.8+ required) |
| references/inquiry-checkpoints.md | Phase 2 — load for per-template investigation questions |
| references/stack-detection.md | Phase 2 — only if stack is ambiguous |
| assets/templates/STACK.md | Phase 3 step 1 |
| assets/templates/STRUCTURE.md | Phase 3 step 2 |
| assets/templates/ARCHITECTURE.md | Phase 3 step 3 |
| assets/templates/CONVENTIONS.md | Phase 3 step 4 |
| assets/templates/INTEGRATIONS.md | Phase 3 step 5 |
| assets/templates/TESTING.md | Phase 3 step 6 |
| assets/templates/CONCERNS.md | Phase 3 step 7 |
Template usage mode: