/featuring

name: featuring
description: >-
  Generate hierarchical _FEATURES.md files that describe what a codebase DOES from a
  user/consumer perspective, anchored to source symbols via tree-sitting. Supports large
  complex codebases through feature-driven decomposition into sub-feature files. Uses a
  multi-pass synthesis: orientation → detail → overview rewrite. Use when someone says
  "what does this do", "document features", "feature inventory", "_FEATURES.md",
  or needs to understand a codebase's purpose before modifying it. Complements
  tree-sitting (structural) with semantic (why/what-for) layer.
metadata:
  version: 0.4.0

Featuring

Generate `_FEATURES.md` files — top-down documentation of what a codebase **does**, organized by feature/capability, anchored to specific source symbols.

**tree-sitting** tells you WHAT symbols exist. **_FEATURES.md** tells you WHY they exist and what they accomplish together.

For large codebases, the root `_FEATURES.md` decomposes into sub-feature files linked by capability area — not by folder structure. An agent starts at the root and is drawn into sub-files only when working on a relevant area.

Dependency

Requires **tree-sitting** skill. Uses its engine for AST scanning.

uv venv /home/claude/.venv 2>/dev/null
uv pip install tree-sitter-language-pack --python /home/claude/.venv/bin/python

tree-sitting caches its scan to `/tmp/treesit-cache`, keyed by repo path plus skip set. That cache persists symbols and imports but NOT file source, so a cache HIT returns `source=None`. `gather.py` re-reads those files from disk; do not assume `entry.source` is populated if you write against the engine directly. (Before this was handled, gather crashed on its second run against a repo while the first succeeded — diagnosed 2026-08-22.)

For quick structural orientation before running gather.py, use tree-sitting's CLI:

TREESIT=/mnt/skills/user/tree-sitting/scripts/treesit.py

# Complete tree, sparse detail — see the full shape
/home/claude/.venv/bin/python $TREESIT /path/to/repo --depth=-1 --detail=sparse

Workflow: Multi-Pass Synthesis

Feature documentation is built in three passes. The overview is written LAST, after all features are understood — not first.

Pass 1: Orientation (quick scan)

/home/claude/.venv/bin/python /mnt/skills/user/featuring/scripts/gather.py /path/to/repo \
  --skip tests,.github,node_modules --source-budget 8000

**`--orient` when you are not writing the file.** The full output is a complete symbol inventory — 5,697 lines on a 71k-line repo — and it exists so a `_FEATURES.md` can cite every symbol. When the deliverable is your own understanding (a review, an orientation read), pass `--orient`: complexity assessment, decomposition ranking, directory tree and entry points, and nothing else. ~115 lines. Reaching for `head` on the full output means `--orient` was the right mode.

Pass 1 of THIS skill is the case that wants the full output — you are about to write the inventory down.

Read the gather output. Before writing anything, form a hypothesis:

> "This codebase appears to be a **[what it is]** that provides **[capability A]**, > **[capability B]**, and **[capability C]**."

Write this down as a DRAFT overview. It will be wrong or incomplete — that's fine. The point is to orient before diving into detail.

**How to identify capability areas:**

1. **What can a user/consumer DO with this?** (commands, API endpoints, UI actions) 2. **What problems does it solve?** (the WHY behind the code) 3. **What are the main workflows?** (how features compose) 4. **What are the constraints/invariants?** (rules the code enforces)

Pass 2: Detailed feature extraction

For each capability area identified in Pass 1:

1. Gather the symbols that implement it (from gather output + targeted `get_source()`) 2. Understand how they collaborate — the workflow 3. Identify constraints and invariants 4. Write the feature section

During this pass, you'll discover:

• Capabilities you missed in Pass 1
• Features that are more complex than expected (decomposition candidates)
• Features that are simpler than expected (merge candidates)
• Cross-cutting concerns that span multiple capability areas

**Hierarchy decision** (per feature, during this pass):

| Signal | Action | |--------|--------| | ≤6 key symbols, self-contained | Inline in root `_FEATURES.md` | | >6 key symbols OR clear sub-capabilities | Own `_FEATURES.md` sub-file | | Spans many files but is ONE capability | Inline (breadth ≠ complexity) | | Has sub-features that are independently useful | Own sub-file | | Is infrastructure (logging, DB layer) | Inline briefly, unless it IS the product |

Pass 3: Overview rewrite

NOW — after all features are documented — rewrite the overview. The Pass 1 draft was a hypothesis. Pass 3 replaces it with a proper progressive-disclosure overview that:

1. States what the codebase is in one sentence 2. Lists the top-level capability areas (3-8 items) 3. For each area that has a sub-file: one sentence + link + "read when" guidance 4. For inline features: just the list entry (detail is below in the same file)

This is the most important part. The overview IS the entry point for every agent session. It must be accurate, complete, and fast to scan.

_FEATURES.md Format

Root file

# Features: {project-name}

> One-sentence description of what this codebase is and does.

**Capability areas:**
- **[Area A]** — one-sentence summary
- **[Area B]** — one-sentence summary → [details](path/to/_FEATURES.md)
- **[Area C]** — one-sentence summary

## {Inline Feature Name}

{2-3 sentences: what this feature does from a user perspective.}

**Key symbols:**
- `file.py#function_name` — role in this feature
- `file.py#ClassName` — role in this feature

**Workflow:** {How a user exercises this feature or how symbols collaborate.}

**Constraints:** {Invariants, limits, rules.}

---

## {Complex Feature Area}

>