# Codebase Analysis

> Use when explicitly asked for $codebase-analysis to create or fully update CURRENT_STATE.md with evidence for the current repository or focused area. Do not use for casual code questions, reviews, implementation, debugging, solution design, or planning.

- Skill: `tony-adamson/codebase-analysis-2` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add tony-adamson/codebase-analysis-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tony-adamson/codebase-analysis-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tony-adamson (https://skillmd.com/u/tony-adamson)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tony-adamson/codebase-analysis-2

---


# Codebase Analysis → CURRENT_STATE.md

The skill creates or fully rewrites `CURRENT_STATE.md` in the directory returned by `pwd`.

The skill's job is to describe **how the system works right now**. Do not propose a future solution, refactoring, migration, new architecture, or an implementation plan.

The resulting file always consists of two blocks:

1. **Block 1. For the human** — a short, readable summary without overload.
2. **Block 2. For the agent** — a detailed evidence-backed snapshot for `$solution-design`, `$planf3`, and review.

## Hard boundaries

You may modify only `CURRENT_STATE.md` and the permitted artifacts of the auxiliary graph, if they are produced by the standard tool.

Forbidden:

- modifying source code, tests, configs, schemas, dependencies, or project documentation;
- creating `SOLUTION.md`;
- designing a future change;
- automatically launching `$solution-design` or `$planf3`;
- commits, pushes, deploys, migrations, cloud write commands;
- turning the analysis into a full-repository audit when the user gave a narrow focus.

## Launch contract

1. Run `pwd` and treat it as the `analysis root`.
2. Determine the Git root, branch, revision, and the initial working tree state. If `pwd` is not the Git root — record that honestly.
3. Read local instructions: `AGENTS.md`, `CLAUDE.md`, README, CONTRIBUTING, architecture documents, build/test/release docs.
4. Find the relevant manifests, schemas, package roots, and code roots.
5. If the user gave a focus — analyze deeply only the related area. If there is no focus — produce a bounded overview, not a file-by-file encyclopedia.
6. Find an existing `$graphify` graph. Use it only as a navigation index. Verify every material conclusion against live code, tests, configs, and schemas.
7. At the end, compare the final working tree with the initial baseline and explicitly separate pre-existing changes from the newly created `CURRENT_STATE.md`.

## Context management

Use read-only subagents adaptively:

- small local area: 0–1;
- several subsystems: 2–3;
- large monorepo: up to 4.

No nested spawning. Each subagent returns only facts, inference, unknowns, evidence, and analysis limitations. Only the coordinator writes the final document.

If the harness does not provide an isolated-subagent tool (for example, Pi) — perform these roles inline as separate passes: a pass outputs only findings in the role's format, then the coordinator continues. Do not simulate spawning subagents and do not claim they were launched.

## Minimality and overengineering protection

Even an analysis of the current state must help future agents **avoid building unnecessary architecture**.

Always record:

- existing simple extension points;
- local patterns worth reusing;
- dependencies and abstractions the project currently does not have;
- places where the project deliberately lives without a global state/service/framework layer;
- complexity constraints that future changes must respect.

Do not call the absence of a framework or layer a problem. Describe it as a fact or a deliberate current style, if the code confirms it.

## What to read

- [analysis-workflow.md](references/analysis-workflow.md) — the order of analysis.
- [evidence-policy.md](references/evidence-policy.md) — evidence rules.
- [repository-lenses.md](references/repository-lenses.md) — universal lenses for mobile/frontend/backend/game/CLI/library/etc.
- [delegation-policy.md](references/delegation-policy.md) — subagents and context limits.
- [CURRENT_STATE.template.md](references/CURRENT_STATE.template.md) — the mandatory structure of the result.

## Language

Write `CURRENT_STATE.md` and all reports in the user's language — the language of the user's request and conversation, **not** the language of these instructions. If the request is in Russian, the artifact is in Russian. Do not translate file names, symbols, commands, statuses, or APIs.

## Completion criteria

`CURRENT_STATE.md` is done only if:

- there is a short human block;
- the agent block contains the evidence-backed current state;
- `FACT`, `INFERENCE`, `UNKNOWN` are explicitly separated;
- contracts, invariants, verification, and unknowns are recorded;
- the simplicity baseline is recorded;
- no future solution is proposed;
- the final working tree has been checked;
- the status is exactly one of: `CURRENT_STATE_COMPLETE` or `CURRENT_STATE_PARTIAL`.