xp

name	xp
description	Brief as reference, not iron plan. Reconstructs intent from owner signal, produces experience spec (actor × surface × planes), gates implementation with divergence report. Pairs with forge.

/xp — Experience-Map Pipeline

Principle. Brief = signal of intent, not literal contract. Job: reconstruct real need from brief + OWNER.md + project context, produce spec that captures what actually serves user across all affected perspectives (actor views × analytical planes), surface divergence honestly, then hand off to forge or direct implementation.

Use when.

• Task touches client- or operator-facing experience
• New capability / UX surface / major UX change
• Brief is vague, reference-mode matters
• Pre-plan gate for anything that touches real people
• Explicitly: user says "xp", "experience", "подумаем перед планом"

Skip when.

• Trivial (typo, CSS refactor no-behavior-change)
• Pure infra (deploy config, dockerfile)
• Emergency hotfix (ship first, spec after)
• Exploratory spike (throwaway)

---

Pipeline (9 phases, scale by risk)

See ~/code/thewhychain/docs/experience-map/_pipeline.md for authoritative reference when working in that repo. In other projects, copy-paste from templates/experience-map/_pipeline.md in this plugin during init.

Phase 0 — Brief Interpretation (mandatory)

Read brief + load ~/.claude/OWNER.md + project CLAUDE.md + existing experience files with matching keywords. Produce Brief Interpretation Memo:

• Literal: what brief says word-for-word
• Likely intent: real job-to-be-done, derived from OWNER.md values
• Alternatives considered: 1-3 ways to serve same need differently
• Confidence: 1-10

Confidence-based branching:

• 8-10: proceed; memo saved, shown at Phase 6
• 5-7: present via AskUserQuestion (literal | interpretation | other)
• 1-4: single open-ended clarifying ask BEFORE running pipeline

Phase 1 — Challenge (mandatory, 4 forcing questions)

• Надо ли это вообще делать?
• Можно ли проще (без стрипания что owner ценит)?
• Можно ли лучше для того же need?
• Для кого и зачем?

Answer as hypotheses. Batch asks to owner via AskUserQuestion. Max 3 asks.

Phase 2 — Deep understanding (iterative, medium+ only)

Claude asks ONLY on real judgment calls. Decides rest from OWNER.md. Max 3 rounds. Round 4 = "enough" OR "need discovery spike".

Phase 3 — Spec drafting

Delegate to xp-drafter agent. Produces experience file(s) per _schema.md v1+v2+v3 rules (5 primitives: Actor/Surface/Experience/Plane/Invariant; R1-R6 rules).

Phase 4 — Self-review (mandatory)

xp-drafter re-reads own draft. Lists gaps, OWNER.md mismatches, overfit-to-literal concerns.

Phase 5 — Codex adversarial pass

Delegate to xp-critic agent. Wraps codex exec with adversarial prompt + R1-R6 reference. Returns BLOCKER/STRONG/WEAK findings. Claude fixes BLOCKERS + most STRONG. Second pass verifies closure.

Phase 6 — Reconciliation with owner

Present via AskUserQuestion:

• Final spec (pointer to files)
• Brief Interpretation Memo
• Divergence Report preview
• Self-review + Codex findings
• Open questions (max 3)

Phase 7 — Spec lock

Commit files. Trailer Experience-impact: <xp-id>. Bump last_verified.

Phase 8 — Divergence Report (mandatory, before ship)

Compare final spec vs literal brief:

• Low (≤10%): logged, not blocking
• Medium (10-30%): one owner confirm via AskUserQuestion
• High (>30%): full report + alternatives, may re-enter Phase 0

Heuristic for %: subject same (0) → surface differs (+10) → scope differs (+10-20) → premise challenged (+20-40).

---

Scale-by-risk cheat

Risk	Phases	Codex	Owner asks
Trivial	0 only	skip	0
Small	0, 1, 3, 7	skip	1 if divergence
Medium	0-7, 8	1 pass	1-2
Large	0-8 full	2+ passes	2-3

---

Agents this skill calls

• beast-forge:xp-drafter — phases 3 + 4. Writes spec with persona-views + plane-notes + conflicts + gaps.
• beast-forge:xp-critic — phase 5. Wraps codex CLI with R1-R6 adversarial prompt.
• beast-forge:xp-reality-updater — post-ship sweep (weekly/monthly). Scans for stale last_verified, drifted metrics.

---

Integration with /forge

/xp → produces spec. /forge → produces plan + TDD steps against that spec.

Flow when owner asks for a task:

1. Claude runs /xp <task> first
2. Phase 0-8 produces experience file(s)
3. Divergence Report approved
4. Hand off to /forge with Experience-impact: <xp-id> trailer in plan
5. FINAL-PLAN references spec files in ## Experience impact section
6. Acceptance criteria in plan = acceptance criteria in spec

Without /xp, /forge runs in literal-mode. For feature work this is usually wrong.

---

OWNER.md requirement

/xp needs ~/.claude/OWNER.md populated with owner's values, anti-patterns, decision style. Without it, Phase 0 degrades to literal-mode (no basis for interpretation).

First-run check: if ~/.claude/OWNER.md does not exist, skill creates skeleton from template and asks owner to fill core Values + Anti-patterns before continuing. Can skip for trivial tasks.

---

Init new project

First time in a project without docs/experience-map/:

1. Copy templates/experience-map/_schema.md → docs/experience-map/_schema.md
2. Copy templates/experience-map/_pipeline.md → docs/experience-map/_pipeline.md
3. Create empty dirs: _actors/, _surfaces/, experiences/
4. Add CLAUDE.md snippet from templates/experience-map/claude-md-snippet.md to project root CLAUDE.md
5. First experience drafted from user's first /xp call; actor/surface files created as referenced

---

Output format of Phase 0 memo

When Claude produces Brief Interpretation, format MUST be:

## Brief Interpretation (Phase 0)

**Literal:** <owner's request, paraphrased once>

**Likely intent:** <the real need, 2-3 sentences referencing OWNER.md values>
  - derived from OWNER.md: [value / anti-pattern IDs that applied]
  - derived from project: [specific facts]
  - derived from existing experience: [xp-id if relevant]

**Alternatives:**
- <alt 1>: <why might be better than literal>
- <alt 2>: <why literal might actually win>

**Confidence:** N/10
**Recommendation:** proceed literal | proceed interpretation | ask to disambiguate

This memo lives in the experience file as section ## Brief Interpretation, between frontmatter and ## Scenario.

---

Output format of Phase 8 divergence report

## Divergence Report

**Brief (literal):** "<exact owner words>"

**Spec (final):** <1-2 sentence summary>

**Divergence points:**
- <point>: <literal vs spec + why change>
- OR: "none — literal matches final"

**Reasoning trace:**
- From OWNER.md: <value X → prioritized Y>
- From existing experience: <xp-id → avoided conflict with W>
- From Codex finding: <adjustment>

**Owner signals needed before implementation:**
- <blocker>
- OR: "none — divergence low, approved at Phase 6"

Logged in experience file as ## Divergence, between ## Acceptance criteria and ## Conflicts.

---

Escalation rules

• Max 3 blocking asks per run (excluding Phase 6 reconciliation)
• Phase 6 itself is 1 ask with multi-select
• Batch where possible
• Critical interrupts (security, irreversible action, OWNER.md anti-pattern violated) bypass budget

---

Anti-patterns for this skill

• Silent reinterpretation — always surface Brief Interpretation
• Running /xp on trivial task — waste; scale down
• Running without OWNER.md populated — waste; skeleton first
• Codex pass on every task — waste; medium+ only
• Owner asks > 3 blocking per run — over-escalation, solve more with OWNER.md
• Writing spec without Phase 0 — literal-mode leak; pipeline incomplete
• Skipping Phase 8 Divergence Report before implementation — contract invisible

---

Commit hygiene

Any commit touching experience files MUST include trailer:

Experience-impact: <xp-id-1>, <xp-id-2>

Any commit implementing against experience spec MUST reference the spec file in body.

---

Retirement criteria

If after 30 days:

• experience files not modified in git log
• no Experience-impact: trailers appear in commits
• no /xp invocations

→ skill is dead weight. Either ritualize enforcement via stricter hooks OR retire skill and return to direct forge.

Maps not read are cargo cult. Honest about this.

---

Version

v0.1 (2026-04-19, initial). Based on 3-session-deep spike in thewhychain/Galevox project. Real-world validated on 6 experience files + 2 codex adversarial passes.