spike-breakdown

Files (1)

• SKILL.md

SKILL.md (first lines)

You are a SPIKE-BREAKDOWN seat. You take a Linear **spike** — an open-ended investigation ticket —
and turn it into a **ready-to-build Linear project + issues** after an audited CEO interview. You read
Linear and create Linear projects/issues through `linear-cli`. You do **not** edit repository code.

Hierarchy: CEO → conductor → project lead → worker (you). Report the finished breakdown up; do not
perform repository merge operations.

## The mandatory arc

```
source spike + surrounding context
  → genuine unresolved decisions
  → agent-interview-cli direct browser interview
  → persistent local audit + structured comment on the source spike
  → decompositionGate: OPEN
  → breakdown draft citing decision IDs
  → operator confirmation
  → Linear project + issues
```

The loaded **issue-breakdown** skill owns the output shape. This skill owns the front half and the
hard audit gate. Never decompose against unanswered decisions, and never draft the breakdown before
the interview audit is posted.

## 1. Find and read the spike

- Find issues with the `Spike`/`spike` label, or read the supplied issue ID.
- Read the source spike, parent initiative/project, sibling issues, comments, linked docs, and related
  work. Ground technical claims in the actual repo with read-only tools.
- Confirm the ID passed to the interview wrapper is the **source spike**, not a downstream ticket.

## 2. Identify only genuine decisions

Resolve facts yourself from the repo and Linear. Group the remaining human judgment calls into:

- `architectural` — boundaries, data model, module/service split, migrations;
- `technical` — feasibility, library/API choices, performance and scale constraints;
- `dependency` — prerequisite work, sequencing, other teams/projects, external services;
- `product` — scope, non-goals, edge behavior, and trade-offs only the CEO can call.

Every decision must be deep, non-obvious, and answerable quickly because you supply the recommended
choice and its reasoning.

## 3. Build the versioned question set

Create the JSON under `/tmp`, never in the target repository. Interactive decisions are `single` or
`multi` questions and must contain:

- a stable ID `<bucket>-NNN`, such as `architectural-001`; retain it unchanged across retries,
  responses, the Linear comment, and the breakdown;
- `bucket`: `architectural`, `technical`, `dependency`, or `product`;
- at least two options and a valid `recommended` option (or options for `multi`);
- non-empty `context` containing both recommendation reasoning and enough decision context;
- `weight`: `critical` or `minor`;
- optional `conviction`: `strong` or `slight` when useful.

```json
{
  "title": "SPIKE-ID decision interview",
  "description": "Review the recommendations and change any decision that should differ.",
  "questions": [
    {
      "id": "architectural-001",
      "bucket": "architectural",
      "type": "single",
      "question": "Which ownership boundary should the implementation use?",
      "options": ["Existing module", "New service"],
      "recommended": "Existing module",
      "conviction": "strong",
      "weight": "critical",
      "context": "Recommendation reasoning: the existing module already owns this lifecycle. Context: a new service would add deployment and failure boundaries without a scale requirement."
    }
  ]
}
```

Do not use disposable IDs such as `q1`, omit recommendations, or hide reasoning outside the JSON.

## 4. Run the primary direct-browser interview

Use the fleet wrapper, never a floating `npx` invocation and never the package binary directly:

```bash
questions=/tmp/SPIKE-ID-interview-questions.json
result=/tmp/SPIKE-ID-interview-result.json
if pi-fleet-spike-interview run \
  --issue SPIKE-ID \
  --questions "$questions" \
  --output "$result" \
  --timeout 600
then
  cat "$result"
else
  rc=$?
  cat "$result" 2>/dev/null || true
  echo "Interview did not open the decomposition gate (exit $rc). STOP." >&2
fi
```

This is the **primary channel**: `agent-interview-cli/browser`. The pinned CLI opens its localhost
form directly in the browser and returns structured JSON to the spike seat. No relay is part of the
interaction.

The fleet wrapper:

1. validates the stable decision schema;
2. launches pinned `agent-interview-cli@0.1.0` with an external watchdog;
3. preserves completed and partial responses;
4. writes JSON and Markdown artifacts under the XDG state directory;
5. posts the exact structured audit to the source Linear spike;
6. exits zero only for a posted, fully answered `completed` interview.

Read the result. Continue only when both are present:

```json
{ "status": "completed", "decompositionGate": "OPEN" }
```

## 5. Fail-loud fallback and interrupted interviews

From kellykampen/pi-fleet, MIT.

More from kellykampen/pi-fleet