skill-review

# Skill Review

**Core responsibility:** Find real behavioral gaps in a Lattice skill by reviewing it through three independent personas. Each persona sees the skill with different eyes, cares about different things, and may surface different gaps. The combined findings should be more practical and complete than any single review.

**Input:** One skill path or skill name.

**Output:** A unified findings report — only the high-confidence, practical gaps from all three personas, merged, deduplicated, pruned, and ordered by severity — with proposed fixes.

**Review standard:** Prefer omission over speculation. Only report findings you are highly confident would surface in normal use, belong to this skill's responsibility, and would materially improve outcomes if fixed. A valid review may conclude that no material practical gaps remain.

**How to verify this skill did its job:**
- Every reported finding is grounded in a realistic scenario and tied to specific evidence in the skill
- Zero findings is acceptable if no high-confidence practical gaps remain
- Every gap has a specific proposed fix, not just a flag
- Overlapping findings from multiple personas are merged into one entry with a note that multiple perspectives agree
- Multiple personas agreeing raises confidence only after the finding survives the practicality filter
- The final report is ordered: critical gaps first, warnings second, observations last — or explicitly says no material practical gaps were found
- After fixes are applied, a second run of this skill on the same skill file shows no high-confidence practical gaps

---

## Step 1: Read the skill

Read the full SKILL.md and all referenced files (defaults.md, template.md, references/).

Form a clear understanding of:
- What the skill claims to do and who uses it
- What it produces (documents, reports, code, changes)
- What its inputs are and what states they can be in
- Where it sits in the Lattice pipeline (upstream / downstream connections)

If the skill is composed by molecules, consumes refiner output, or depends on other skills, read the relevant upstream/downstream files too. Review against actual runtime usage, not an imagined standalone use case.

---

## Step 2: Propose 3 review personas

Based on what the skill does and who it serves, propose 3 personas whose perspectives would surface the most useful gaps.

**Persona selection logic:**

| If the skill... | Consider personas like... |
|---|---|
| Is a molecule used by product/BA people | Senior PM, Business Analyst, Lead Developer consuming the output |
| Is an atom enforcing code quality | Code reviewer, Junior developer following the rules, Architect checking for structural gaps |
| Is a refiner configuring standards | Team lead setting standards, New team member onboarding, AI assistant consuming the standards doc |
| Is a dev-tool skill (forge, validator, sync) | Lattice maintainer, First-time skill creator, Experienced developer new to Lattice |
| Spans product + technical audiences | One product persona, one practitioner persona, one technical persona |

Present 3 proposed personas with a one-line rationale for each:

*"For [skill-name], I'd review from these three perspectives:*
*1. [Persona A] — because [why this skill matters to them / what they'd be looking for]*
*2. [Persona B] — because [different angle this persona brings]*
*3. [Persona C] — because [third angle, ideally the consumer of the skill's output]*

*Want to use these, swap any out, or add your own?"*

Wait for the user to confirm or adjust before proceeding.

**Do NOT proceed to Step 3 until personas are agreed.**

---

## Step 3: Persona analysis (run all three independently)

For each persona in sequence, fully inhabit that perspective. Forget the other personas while you are in one.

### For each persona, run this analysis:

**3a — Scenario generation**

Generate the smallest realistic set of scenarios needed to stress this skill (typically 4–6; do not force all scenario types). Consider:
- The ideal case (everything is as the skill expects)
- First-time use (no existing setup, no prior knowledge)
- Resuming interrupted work (some output already exists)
- Minimal input (user provides as little as possible)
- Maximal / complex input (large scope, many items, messy material)
- The "wrong" input (material at the wrong granularity, the wrong format, a misunderstood concept)
- Declining the recommended path (user skips a suggestion and wants to proceed differently)
- Conflicting inputs (two sources that say different things)

Use only the scenarios that genuinely apply to this skill. Skip any case that does not fit. Better 4 relevant scenarios with real findings than 8 forced scenarios with speculative ones.

For each chosen scenario, follow the skill's instructions literally. Treat silence as a gap only if ALL are true:
- The scenario is realistic in normal use
- The decision belongs to this skill rather than another skill or pipeline stage
- The missing guidance would likely cause a real failure, confusion, or drift

If any of these are false, do not record a finding.

**3b — Persona-specific concerns**

Use these as attention prompts, not finding quotas. They help you notice classes of problems; they do not guarantee that a real finding exists.

Each persona has things they care about that others might miss:

- **A practitioner or user persona** asks: "Is this skill telling me what to do at every decision point? Or am I guessing?" May surface: gaps in decision guidance, missing error handling, ambiguous instructions.
- **A quality or standards persona** asks: "Are the rules here enforceable? Can I tell pass from fail?" May surface: vague criteria, missing boundary conditions, rules that contradict each other.
- **A technical or architectural persona** asks: "Does this compose correctly? Does it stay in its lane?" May surface: missing cross-references, scope bleed, broken upstream/downstream handoffs, missing resume logic.
- **A product or o