acquire-codebase-knowledge

Acquire Codebase Knowledge

Produces seven populated documents in docs/codebase/ covering everything needed to work effectively on the project.

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

Workflow

- [ ] 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

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
   

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.

Phase 3: Populate Templates

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 — test frameworks, coverage, CI
7. CONCERNS.md — tech debt, risks, open questions