feature-benefits

# Feature-Benefits Extraction

Scan a codebase systematically, extract concrete features with evidence, classify by impact, and translate into benefit-driven language for documentation.

## 7-Step Feature Extraction Workflow

### Step 1: Detect Project Type

Read the primary manifest to understand the ecosystem:

| File | Ecosystem | Key Fields |
|------|-----------|------------|
| `package.json` | Node.js / JavaScript / TypeScript | `dependencies`, `scripts`, `bin`, `exports`, `type` |
| `pyproject.toml` | Python | `[project.dependencies]`, `[project.scripts]`, `[tool.*]` |
| `Cargo.toml` | Rust | `[dependencies]`, `[features]`, `[[bin]]` |
| `go.mod` | Go | `require`, module path |
| `.claude-plugin/plugin.json` | Claude Code Plugin | `skills`, `commands`, `agents`, `hooks` |

Also check: `Makefile`, `Dockerfile`, `docker-compose.yml`, `.github/workflows/`, `wrangler.toml` for deployment signals.

### Step 2: Scan Signal Categories

Scan the 10 signal categories: CLI Commands, Public API, Configuration, Integrations, Performance, Security, TypeScript/DX, Testing, Middleware/Plugins, Documentation.

For each category, check file patterns, read matching files, and record what you find. For detailed file patterns and scan lists per category, load `SKILL-signals.md` from this skill directory.

### Step 3: Extract Concrete Features with Evidence

For each signal found, create a feature entry:

```
Feature: [What it does — concrete, specific]
Evidence: [File path, function name, or config that proves it]
Category: [Signal category from Step 2]
```

**Rules:**
- Every feature must have a file path or function as evidence
- No speculative features — if you can't point to code, it's not a feature
- Be specific: "Zero-config TypeScript support" not "Good developer experience"

### Step 3.5: Map to Jobs-to-be-Done (Hero features only)

For Hero features, frame the job: `When I am [situation], I want [capability], so I can [outcome]`. Classify as Functional, Emotional, or Social. Skip JTBD for Core/Supporting tiers and projects with fewer than 5 features. For full JTBD guidance, load `SKILL-signals.md`.

### Step 3.6: Persona Inference

Infer 1–2 target personas from code signals (integration surface, execution model, entry points, deploy artifacts). Map to archetypes: Solo builder, Team lead, Platform/ops engineer, Power user/automator, Compliance-aware org. Default to "Solo builder" if ambiguous. For the full persona inference table, load `SKILL-signals.md`.

### Step 4: User Benefits (the "Why?" Layer)

User benefits answer **"Why should I care?"** — the real-world reasons someone would choose this project.

**Two paths available — both produce the same output format:**

#### Path A: Auto-Scan (default)

Synthesise outcome-first benefits from Hero features + JTBD + persona:
1. Apply the **signal gate**: Standard (workflow benefits) by default; Elevated (experiential) only with mobile/async/remote/voice signals in code
2. Generate 3–7 draft benefits, tag claim strength: Strong (code directly enables), Medium (reasonable inference), Weak (discard)
3. Ship only Strong + Medium benefits

#### Path B: Conversational ("Talk it out")

Use 4 interactive questions to surface authentic use cases, then enrich with code evidence. For the full prompt sequence, load `SKILL-signals.md`.

#### Output Format

```
**[Bold user outcome]** — [mechanism/how it works]. [Constraint if needed].
```

Each benefit requires: a specific context, an enabling mechanism, and an evidence pointer.

### Step 5: Classify by Impact Tier

| Tier | Count | Criteria | README Placement |
|------|-------|----------|-----------------|
| **Hero** | 1–3 | Primary differentiators — why someone chooses THIS over alternatives | One-liner, Why section, first in features |
| **Core** | 4–8 | Expected by the target audience — missing these would be a deal-breaker | Features table, quick start examples |
| **Supporting** | 9+ | Nice-to-have — adds polish but isn't the reason someone adopts | Mentioned briefly or linked to docs |

### Step 6: Output Structured Feature Inventory

Output as a Markdown table with Feature, Evidence, Benefit Category, and optional JTBD columns, grouped by tier (Hero, Core, Supporting). Or use emoji+bold+em-dash bullets for direct README use.

---

## Feature-to-Benefit Translation Framework

### The Translation Pattern

```
[Technical feature] so you can [user outcome] — [evidence]
```

### 5 Benefit Categories

Use at least 3 different categories across your features table:

| Category | Pattern | Example Benefit |
|----------|---------|----------------|
| **Time saved** | "Do X in Y instead of Z" | "Generate a full README in under a minute — not an afternoon" |
| **Confidence gained** | "Know that X because Y" | "Every benefit traces to actual code — no marketing fluff" |
| **Pain avoided** | "Never worry about X" | "Never ship a repo with missing docs again" |
| **Capability unlocked** | "Now you can X" | "Scan any codebase and extract its selling points automatically" |
| **Cost reduced** | "Save X by Y" | "One plugin replaces five separate documentation tools" |

### Anti-Patterns

- **No "simple" or "easy"** — show simplicity through a short code example
- **No "powerful" without evidence** — what specifically makes it powerful?
- **No speculative benefits** — "could save you hours" requires evidence
- **No feature-as-benefit** — "Has caching" is a feature; "Responses in <50ms after first request" is the benefit
- **No benefit without context** — every user benefit needs a specific situation
- **No benefit without mechanism** — every user benefit needs an enabling mechanism
- **No ungrounded lifestyle claims** — elevated signal gate only when code proves the mechanism

For the full translation table by signal category, badge mapping, and common patterns library, load `SKILL-signals.md`.