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

name, description

name	description
analyzing-codebase-for-tech-log	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.

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.