acquire-codebase-knowledge

# Acquire Codebase Knowledge 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. ## Output Contract (Required) Before finishing, all of the following must be true: 1. Exactly these files exist in `docs/codebase/`: `STACK.md`, `STRUCTURE.md`, `ARCHITECTURE.md`, `CONVENTIONS.md`, `INTEGRATIONS.md`, `TESTING.md`, `CONCERNS.md`. 2. Every claim is traceable to source files, config, or terminal output. 3. Unknowns are marked as `[TODO]`; intent-dependent decisions are marked `[ASK USER]`. 4. Every document includes a short "evidence" list with concrete file paths. 5. Final response includes numbered `[ASK USER]` questions and intent-vs-reality divergences. ## Workflow 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 ``` ## Focus Area Mode If the user supplies a focus area (for example: "architecture only" or "testing and concerns"): 1. Always run Phase 1 in full. 2. Fully complete focus-area documents first. 3. For non-focus documents not yet analyzed, keep required sections present and mark unknowns as `[TODO]`. 4. Still run the Phase 4 validation loop on all seven documents before final output. ### Phase 1: Scan and Read Intent 1. Run the scan script from the target project root: ```bash 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: ```bash python3 /absolute/path/to/skills/acquire-codebase-knowledge/scripts/scan.py --output docs/codebase/.codebase-scan.txt ``` 2. Search for `PRD`, `TRD`, `README`, `ROADMAP`, `SPEC`, `DESIGN` files and read them. 3. Summarise the stated project intent before reading any source code. ### Phase 2: Investigate Use the scan output to answer questions for each of the seven templates. Load [`references/inquiry-checkpoints.md`](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`](references/stack-detection.md). ### Phase 3: Populate Templates Copy each template from `assets/templates/` into `docs/codebase/`. Fill in this order: 1. [STACK.md](assets/templates/STACK.md) — language, runtime, frameworks, all dependencies 2. [STRUCTURE.md](assets/templates/STRUCTURE.md) — directory layout, entry points, key files 3. [ARCHITECTURE.md](assets/templates/ARCHITECTURE.md) — layers, patterns, data flow 4. [CONVENTIONS.md](assets/templates/CONVENTIONS.md) — naming, formatting, error handling, imp