document-haness/.agents/skills/analyzing-codebase-for-tech-log/SKILL.md

---
name: analyzing-codebase-for-tech-log
description: Use when a project under <분석 대상 저장소> must be deeply analyzed and documented under docs, especially when the repository is too large for one pass and analysis must proceed by bounded module or subsystem.
metadata:
  version: "1.0.0"
  language: "ko-KR"
---

# Analyzing Codebase For Tech Log

## Goal

Produce a highly detailed, source-traceable engineering analysis. This stage discovers facts and evidence; it does **not** write Tech Log records yet.

## Required sequence

0. **Fix the two roots before anything else.** `<분석 대상 저장소>` is the repository being analyzed — an absolute path outside this repository, given by the caller. `docs/<프로젝트>/` is inside *this* repository. Never write into the analyzed repository, and never read analysis state from it.
1. **Read `<분석 대상 저장소>/analysis-queue.yaml` if it exists.** It exists only when several repositories are queued. Apply `references/queue-contract.md`: reconcile newly discovered project directories, preserve queue order, and determine the single active project. **If there is no queue, analyze the one repository the caller named and skip to step 3.** A missing queue is not a blocker — it means nothing is queued.
2. If an `IN_PROGRESS` project exists, analyze only that project. If none exists, activate the first `PENDING` project in queue order. Never preempt an active project because a new project appeared.
3. For the selected `<분석 대상 저장소>`, check the nearest `AGENTS.md` or equivalent repository instructions.
4. Record Git revision and `git status` when Git is available. Never modify or reset user source as part of analysis.
5. Read `docs/<프로젝트>/state.json` if it exists; otherwise initialize the working material from `templates/` in this skill. The project folder template (`docs/_templates/`) holds only the finished shape and does not carry it.
6. Map repository/build/module boundaries before choosing a scope.
7. If the repository is large, select one bounded unanalysed module/subsystem and analyze it completely. Do not skim the whole repository and call that detailed analysis.
8. Update `source-index.md`, the bounded analysis file, coverage ledger, evidence, and `state.json`.
9. Capture runtime evidence only where it resolves a material uncertainty or verifies a significant claim.
10. Continue the same project across runs until all intended scopes are complete.
11. **Fold the analysis into `final/document.md`.** Not a summary of it — the material
    itself, with provenance and limitations intact. The test is that every claim a Tech Log
    record will cite can be anchored in `final/document.md` alone. Anything that survives
    only in `analysis/**` has not been folded in.
12. **Remove the working material.** `analysis/`, `notes/`, `checkpoints/`, `state.json`,
    and `source-index.md` exist only while the analysis runs. A finished project folder
    holds `final/` and `tech-log-studio/` (and `source/` when the material came from
    outside). Then mark the queue entry `COMPLETE` and clear `activeProject`. Do not start
    the next project before this completion transition.

`python3 scripts/fold-analysis-into-final.py <project>` performs steps 11 and 12: it moves
the module analyses into part 2 of `final/document.md`, the source index, scope coverage and
process notes into part 3, rewrites every `analysis/NN` anchor to `final/document.md#aNN`,
and removes the working material.

`analysisStatus: COMPLETE` while the working material is still on disk means step 11 was
skipped — the analysis was summarized rather than folded in, and downstream records will
anchor on `analysis/**` instead of the SSOT. `scripts/verify-project-layout.py` and
`scripts/verify-tech-log-tree.py` count that state.

Read `references/queue-contract.md`, `references/analysis-contract.md`, `references/deep-analysis-standard.md`, and `references/evidence-contract.md` before analysis.

## Evidence vocabulary

Label statements internally as:

- **observed:** directly seen in code/config/test/runtime/git evidence;
- **inferred:** conclusion logically derived from observed sources;
- **hypothesis:** plausible explanation not yet verified;
- **unknown:** material information not available;
- **external:** knowledge from outside the codebase, clearly separated from project observation.

Do not turn inference into observation in the final document.

## Depth rule

A selected bounded scope is an **exhaustive-reading unit**, not a representative-sampling unit. Build an inventory first, then account for every production source/config/build/migration/test file that materially belongs to that scope. Each item must be marked `FULL_READ`, `STRUCTURAL_ONLY`, or `EXCLUDED` with a reason. `EXCLUDED` is allowed only when dependency/import/ownership evidence shows it does not contribute to the scope being documented.

For the selected scope, trace representative behavior end-to-end where applicable: entry point → application policy → domain/state → persistence/external adapter → observable result. Also trace failure paths, transactions, concurrency, lifecycle, configuration, tests, build-time enforcement, runtime wiring, dead/unwired paths, and historical bug/decision evidence when they materially affect the architecture.

Do not stop at "what classes exist". Explain **why the shape exists** only when code comments, tests, design docs, Git history, runtime evidence, or a clearly labeled inference supports the explanation.

There is no target document length. A 3,000+ line module analysis is acceptable when the source warrants it; artificial verbosity is not. Completeness is judged by the coverage ledger and source traceability, not by prose length.

## Stop conditions

Do not run destructive/state-changing commands merely to create evidence. Do not expose secrets. If a runtime check would alter production or shared external state, leave it as an evidence task instead.