mirror of
https://github.com/azaion/annotations.git
synced 2026-04-22 22:26:31 +00:00
Oleksandr Bezdieniezhnykh
72 lines
3.5 KiB
Markdown
72 lines
3.5 KiB
Markdown
---
|
||
name: document
|
||
description: |
|
||
Bottom-up codebase documentation skill. Analyzes existing code from modules up through components
|
||
to architecture, then retrospectively derives problem/restrictions/acceptance criteria.
|
||
Produces the same _docs/ artifacts as the problem, research, and plan skills, but from code
|
||
analysis instead of user interview.
|
||
Trigger phrases:
|
||
- "document", "document codebase", "document this project"
|
||
- "documentation", "generate documentation", "create documentation"
|
||
- "reverse-engineer docs", "code to docs"
|
||
- "analyze and document"
|
||
category: build
|
||
tags: [documentation, code-analysis, reverse-engineering, architecture, bottom-up]
|
||
disable-model-invocation: true
|
||
---
|
||
|
||
# Bottom-Up Codebase Documentation
|
||
|
||
Analyze an existing codebase from the bottom up — individual modules first, then components, then system-level architecture — and produce the same `_docs/` artifacts that the `problem` and `plan` skills generate, without requiring user interview.
|
||
|
||
## File Index
|
||
|
||
| File | Purpose |
|
||
|------|---------|
|
||
| `workflows/full.md` | Full / Focus Area / Resume modes — Steps 0–7 (discovery through final report) |
|
||
| `workflows/task.md` | Task mode — lightweight incremental doc update triggered by task spec files |
|
||
| `references/artifacts.md` | Directory structure, state.json format, resumability, save principles |
|
||
|
||
**On every invocation**: read the appropriate workflow file based on mode detection below.
|
||
|
||
## Core Principles
|
||
|
||
- **Bottom-up always**: module docs → component specs → architecture/flows → solution → problem extraction. Every higher level is synthesized from the level below.
|
||
- **Dependencies first**: process modules in topological order (leaves first). When documenting module X, all of X's dependencies already have docs.
|
||
- **Incremental context**: each module's doc uses already-written dependency docs as context — no ever-growing chain.
|
||
- **Verify against code**: cross-reference every entity in generated docs against actual codebase. Catch hallucinations.
|
||
- **Save immediately**: write each artifact as soon as its step completes. Enable resume from any checkpoint.
|
||
- **Ask, don't assume**: when code intent is ambiguous, ASK the user before proceeding.
|
||
|
||
## Context Resolution
|
||
|
||
Fixed paths:
|
||
|
||
- DOCUMENT_DIR: `_docs/02_document/`
|
||
- SOLUTION_DIR: `_docs/01_solution/`
|
||
- PROBLEM_DIR: `_docs/00_problem/`
|
||
|
||
Optional input:
|
||
|
||
- FOCUS_DIR: a specific directory subtree provided by the user (e.g., `/document @src/api/`). When set, only this subtree and its transitive dependencies are analyzed.
|
||
|
||
Announce resolved paths (and FOCUS_DIR if set) to user before proceeding.
|
||
|
||
## Mode Detection
|
||
|
||
Determine the execution mode before any other logic:
|
||
|
||
| Mode | Trigger | Scope | Workflow File |
|
||
|------|---------|-------|---------------|
|
||
| **Full** | No input file, no existing state | Entire codebase | `workflows/full.md` |
|
||
| **Focus Area** | User provides a directory path (e.g., `@src/api/`) | Only the specified subtree + transitive dependencies | `workflows/full.md` |
|
||
| **Resume** | `state.json` exists in DOCUMENT_DIR | Continue from last checkpoint | `workflows/full.md` |
|
||
| **Task** | User provides a task spec file AND `_docs/02_document/` has existing docs | Targeted update of docs affected by the task | `workflows/task.md` |
|
||
|
||
After detecting the mode, read and follow the corresponding workflow file.
|
||
|
||
- **Full / Focus Area / Resume** → read `workflows/full.md`
|
||
- **Task** → read `workflows/task.md`
|
||
|
||
For artifact directory structure and state.json format, see `references/artifacts.md`.
|