EVOLV/.claude/skills/README.md

Workflow skills — grill-me → prd → prd-to-issues → ship-it

A four-skill chain that takes a vague feature idea from "I want to build X" to merged, end-to-end-verified code. Two phases are collaborative (you + Claude), two run autonomously (AFK).

/grill-me <topic>      TOGETHER   pressure-test the idea
       ↓
/prd                   TOGETHER   synthesize a PRD; gaps stay explicit
       ↓
/prd-to-issues         MOSTLY     thin vertical-slice issues; file when you say "create"
       ↓
/ship-it               AFK        shell loop ships every slice end-to-end

The TOGETHER vs AFK distinction

Mode	Meaning	Skills
TOGETHER	Needs your judgment every turn. No autonomous path.	grill-me
MOSTLY TOGETHER	Drafts/audits AFK, but a visible-to-team action needs your "go".	prd, prd-to-issues
AFK	No human in the loop. Logs questions to issues instead of asking.	ship-it

Each skill's SKILL.md declares its mode in the first body line. The chain is designed so the AFK phase only starts after the human-locked phases have nailed down the contract (PRD requirements, slice acceptance criteria) — AFK code only ships against decisions that already exist on paper.

---

When to use each

/grill-me <topic> — TOGETHER

Use when: you have a fuzzy idea and want it pressure-tested before committing to scope. Also useful for interview prep on any technical topic.

Behavior: acts as a senior staff engineer running a brutal-but-fair interview. One hard question at a time, honest critique (no praise filler), drills into weak spots, demands specifics over buzzwords. Stay on the topic until exhausted; say stop for an honest 3-bullet debrief.

Don't use it for: rubber-stamping a finished idea, or when you want validation. It's designed to find gaps, not to agree with you.

/prd — TOGETHER (drafts AFK after grilling)

Use when: the grilling exposed enough that you're ready to lock down what's being built. Or standalone when you already know the feature shape.

Behavior: writes an engineering PRD (Problem, Goals, Non-goals, Users & scenarios, Functional + Non-functional requirements, Constraints, Success metrics, Open Questions, Out of scope). Things you nailed in the grilling become firm requirements. Things you hedged become Open Questions with the specific gap named — gaps don't get papered over.

Output: inline by default. Say "save it" → writes to docs/prd/<name>.md.

Don't use it for: strategy docs, market sizing, or "why now" sections. This is for engineering.

/prd-to-issues — MOSTLY TOGETHER

Use when: you have a PRD (just-drafted or path-pointed) and need a backlog of issues a team can pick up.

Behavior: breaks the PRD into thin vertical slices — each issue cuts end-to-end through every integration layer (schema → service → API → UI → tests; or sensor → broker → parser → store → dashboard). The first slice is a walking skeleton. Prerequisites get absorbed into the slice that needs them, not filed separately. Each issue has a visible Slice check block proving every layer is covered, plus a coverage matrix at the top of the draft showing PRD → issue mapping. Self-audit runs before drafting is shown to you.

Output: draft inline → you reply create → it files to the tracker (gh for GitHub, tea for Gitea).

Don't use it for: horizontal task lists ("DB work", "API work", "frontend work"). The skill rejects layer-cake slicing — if your work needs that, you want a different tool.

/ship-it — AFK

Use when: issues are filed, you want to walk away, you'll review the PRs later.

Behavior: runs a shell loop that picks the next ready issue, dispatches a fresh headless Claude to ship it end-to-end (failing e2e test first → implement layer by layer → full suite → outermost-layer smoke check → commit Closes #N → PR with checked acceptance criteria + smoke evidence → CI gate → merge or leave-for-review), then moves on. One commit per issue. Status streams to the terminal; you can tail -f the log from another shell or Ctrl-C anytime.

Undecidable issues get labeled needs-decision and skipped. Three consecutive failures stops the loop for human review.

Don't use it for: issues whose acceptance criteria aren't testable (the loop will skip them), or for slices that need real-world side effects with no test harness.

---

A worked example

You want to add live sensor display for a new flow meter on a dashboard.

# 1. Pressure-test the idea
/grill-me adding live flow-meter readings to the operator dashboard

# (you answer 6-8 hard questions; gaps surface)

# 2. Lock down the contract
/prd

# (PRD drafts; you edit one section; save it)

# 3. Slice it
/prd-to-issues

# (draft shows ~5 slices, each with a Slice check block. Coverage matrix
# confirms every PRD requirement maps to a slice. Reply `create`.)
# → issues #142..#146 filed

# 4. Walk away
/ship-it

# (preflight, plan, "Start? Reply `go`." → `go` → shell loop runs)
# In another terminal: tail -f .ship-it-logs/run-*.log

After the loop exits, the summary tells you what shipped, what's open for review, what hit needs-decision.

---

Configuration

Repo trunk branch

ship-it defaults to main. If your repo uses something else:

SHIP_IT_TRUNK=development bash .claude/skills/ship-it/loop.sh

Other env vars

Var	Default	Purpose
SHIP_IT_MAX	50	Iteration cap
SHIP_IT_MAX_FAIL	3	Consecutive failures before stop
SHIP_IT_TIMEOUT	30m	Per-issue timeout
SHIP_IT_LOG_DIR	<repo>/.ship-it-logs	Log directory

Tracker support

• GitHub — uses gh CLI (must be installed and authenticated: gh auth status).
• Gitea — uses tea CLI (must be installed: go install code.gitea.io/tea@latest, then tea login add).
• Auto-detected from git remote get-url origin.

Issue label expected by ship-it

The loop filters to open issues with label slice and without labels blocked, needs-decision, or ci-failed. /prd-to-issues applies the slice label by default. If you file issues by hand, add the label or ship-it won't pick them up.

---

File layout

.claude/skills/
├── README.md                  ← this file
├── grill-me/
│   └── SKILL.md
├── prd/
│   └── SKILL.md
├── prd-to-issues/
│   └── SKILL.md
└── ship-it/
    ├── SKILL.md               ← entry point; chat-side bootstrap
    ├── loop.sh                ← orchestrator (the actual loop)
    └── iterate.md             ← per-issue prompt the loop dispatches

---

Troubleshooting

ship-it won't start: "tea CLI not installed". The repo's remote is Gitea but you don't have tea. Install it (go install code.gitea.io/tea@latest && tea login add) or push to a GitHub mirror.

ship-it exits immediately: "git tree is dirty". Commit or stash everything before running. The loop won't risk mixing your work-in-progress into a slice.

ship-it says "backlog empty" but I have open issues. The filter requires label slice AND no blocked/needs-decision/ci-failed. Add the label, or check what's blocking.

An issue keeps getting needs-decision. Its acceptance criteria probably aren't testable at the outermost layer. Open the issue, rewrite criteria so they're observable (e.g. "POST /x returns 201 and row appears on dashboard" not "feature works"), remove the label, the loop will pick it up next run.

Three failures in a row, loop stopped. Something systemic — bad dependency, branch protection blocking, flaky test env. Check .ship-it-logs/iter-*.log for the per-issue detail.

Issue had a PR opened but didn't merge. Branch protection requires human review. The loop reports it as "shipped → open for review" and moves on. Review and merge when you can.

---

Design principles

• Vertical slices, always. No "implement the backend first, then the frontend". Every issue exercises every layer.
• Gaps are explicit, never hidden. Hedged answers in grilling → Open Questions in PRD → needs-decision issues, not silent assumptions.
• AFK only after the contract is locked. Autonomous code only ships against decisions that already exist on paper.
• One commit per slice. Small, reviewable, revertible.
• Outermost-layer verification. "Tests pass" isn't enough — the loop confirms the user-observable behavior actually works before reporting shipped.