Review Current State

Produce a single up-to-date reference document for the project: a file tree plus a "factblock" for every function, method, and class, in a fixed, reusable template. This is a snapshot skill — it reads the current code, it does not modify it.

Before doing anything else, read .claude/skills/rules/review-current-state.md (scope of review, exclusions, output path) and .claude/rules/scope-and-safety.md (filesystem write scope and safety boundaries every skill/agent follows) — both may be updated over time without this file changing.

Logging

Before Step 1, open this run's log file per .claude/rules/logging.md (name: review-current-state-<time>-<user>.log). Append one entry per step below as it happens.

Scope

See .claude/skills/rules/review-current-state.md for the exact scope/exclusion rules and output path policy.

Steps

1. Enumerate files. Use Glob/Bash (git ls-files is the cleanest source of truth if in a git repo — it naturally skips ignored build/venv directories) to list every tracked file in scope.

2. Build the file tree. Render it as a fenced text block showing the directory hierarchy, e.g.:

   fat_llama_fftw/
   ├── __init__.py
   ├── audio_fattener/
   │   └── feed.py
   └── tests/
       └── test_feed.py
   

   Keep non-code files (README, setup.py, requirements.txt, etc.) in the tree for completeness, but only factblock actual source files (see next step).

3. Read every source file (.py, or the project's primary language) in scope with the Read tool — do not skip files to save time; the point of this skill is completeness. For each file, identify every module-level function, class, and method (including __init__ when it does non-trivial setup).

4. Write one factblock per function/method/class, using this exact template so the output stays reusable and parseable by later tooling or skills:

   ### `qualified.name(args) -> ReturnType`
   **File:** path/to/file.py:LINE
   **Kind:** function | method | class
   **Description:** One or two sentences on what it does and why it exists (pull from the docstring if present; otherwise infer from the body — say so if inferred).
   **Parameters:**
   - `arg` (`type`): meaning
   **Returns:** type and meaning (omit for classes/void functions).
   **Usage:**
   \`\`\`python
   # minimal, runnable-looking example
   \`\`\`
   

   For the usage example: prefer lifting real call sites from the codebase's own tests or example.py-style scripts when one exists for that function; only synthesize a minimal example when no real call site is found, and mark it # illustrative in that case.

5. Assemble the document in this order: title, scope note, file tree, then factblocks grouped under a ## path/to/file.py heading per file, in file-tree order.

6. Write the output to docs/CURRENT_STATE.md at the repo root (create the docs/ directory if it doesn't exist), overwriting any previous version — this file is meant to be regenerated on demand, not hand-edited. If the user specifies a different output path in args, use that instead.

7. Report back with a short summary: number of files reviewed, number of factblocks written, and the output path — not the full document contents.