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:

   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
   

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 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.

Phase 3: Populate Templates

Copy each template from assets/templates/ into docs/codebase/. Fill in this order:

1. STACK.md — language, runtime, frameworks, all dependencies
2. STRUCTURE.md — directory layout, entry points, key files
3. ARCHITECTURE.md — layers, patterns, data flow
4. CONVENTIONS.md — naming, formatting, error handling, imports
5. INTEGRATIONS.md — external APIs, databases, auth, monitoring
6. TESTING.md — frameworks, file organization, mocking strategy
7. CONCERNS.md — tech debt, bugs, security risks, perf bottlenecks

Use [TODO] for anything that cannot be determined from code. Use [ASK USER] where the right answer requires team intent.

Phase 4: Validate, Repair, Verify

Run this mandatory validation loop before finalizing:

1. Validate each doc against references/inquiry-checkpoints.md.
2. For each non-trivial claim, confirm at least one evidence reference exists.
3. If any required section is missing or unsupported:

• Fix the document.
• Re-run validation.

4. Repeat until all seven docs pass.

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:

• No unsupported claims.
• No empty required sections.
• Unknowns use [TODO] rather than assumptions.
• Team-intent gaps are explicitly marked [ASK USER].

Gotchas

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.

…