petal-power/plan-interview-skill
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

project init

Browse Source
This commit is contained in:
Travis Herbranson 2026-05-23 20:16:56 -04:00
commit 5ddf840473
2 changed files with 382 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

227
plan-interviewer/SKILL.md Normal file
View File

@ -0,0 +1,227 @@
---
name: plan-interviewer
description: Conduct a structured interview to develop a project plan into spec-driven shape before handing it to an agent for build. Trigger whenever the user says "let's interview" or any close variant ("interview me", "let's do the interview", "run the interview"). Also trigger when the user asks to review, validate, gate, or stress-test a draft plan, or when they say a plan is ready for agent execution and want a final pass. This skill walks the user through 42 questions across five sections (Spec, Plan, Tasks, Constitution, Cross-cutting + pre-mortem), produces a polished markdown plan artifact in chat, and captures interview-close telemetry for a later retrospective. Use it for any plan substantial enough that an agent will execute it — not for one-off scripts or trivial work.
---
# Plan Interviewer
A skill that conducts a structured pre-implementation interview on a project plan, producing a spec-driven plan artifact ready for agent execution.
## When this fires
Trigger phrase: **"let's interview"** or any close variant. Also fires when the user wants a final review/gate on a plan before agent execution.
Do NOT fire for:
- Trivial one-off work (one-hour scripts, casual experiments)
- Active debugging or troubleshooting sessions
- Requests for code, not planning
If the user invokes the skill but the work is clearly too small to benefit, say so and offer to skip the interview. Don't burn 42 questions on a 30-line script.
## The interview's purpose
The user is a solo developer who plans projects free-form, then hands them to an agent (Claude Code / Lovebug) for build. The interview's job is to close coverage gaps in the plan so the agent needs **≤3 rounds of clarifying questions** when build begins. That's the success metric.
The user has explicitly chosen sectioned-document output (not separate spec/plan/tasks files), retains free-form planning as the front-end, and uses this interview as a structured gate before commit. Respect that. Don't push for Spec Kit's full ceremony.
## Inputs
Free-form. The user might arrive with:
- A complete plan draft (in vault, attached, or pasted)
- Rough notes
- Just a topic ("I want to plan X")
- A conversation history where the plan has been emerging
The skill detects mode from what's in context — no need to ask explicitly.
## Mode detection
**Review mode** — Substantial material exists (draft plan or detailed notes covering most sections). Ask only gap-filling questions. Skip questions whose answers are already on the page.
**Generate mode** — Just a topic or rough idea. Walk through all questions in order to populate the plan.
**Hybrid** — Most common. Some sections solid, others thin. Per-section judgment: light pass where solid, full pass where thin.
State the detected mode at the open: "Looks like review mode — you've got most of Spec and Plan covered. I'll focus on gaps. Push back if you'd rather start from scratch."
## Question set
All 42 questions live in `references/questions.md`. Read that file at the start of every interview session. Sections:
- Spec — 12 questions
- Plan — 17 questions
- Tasks — 4 questions
- Constitution — 4 questions
- Cross-cutting (incl. pre-mortem) — 5 questions
Don't memorize the questions from any general knowledge of SDD frameworks. The questions in `references/questions.md` are the working set, tuned to this user's workflow.
## Flow rules
These are the behaviors that distinguish this interview from a checklist.
### Always acknowledge skipped questions
If a question is being skipped (because context already answered it, or the user said n/a), say so. Brief is fine: "Skipping #5 — covered in your description." The user wants to know what's happening, not to be surprised by gaps.
### Cadence: one question at a time
Ask one question, wait for the answer, then proceed. Don't queue up multiple questions in one turn unless they're tightly coupled (e.g., the EARS conversion shows the converted form and asks for confirmation in the same turn — that's one logical exchange).
### Three skip flavors, supported implicitly
The user controls pacing through their phrasing:
- **Whole section skip** — "constitution doesn't apply, project's too small" → confirm and move to next section
- **Single question skip** — "n/a" or "skip" or "doesn't apply" → silently move on
- **Section condensed** — "I'll answer this in one paragraph" → take the brain-dump, ask targeted follow-ups only for what's missing
Don't ask which mode they're in. Detect from how they respond.
### Push back on weak answers — once, then accept
Apply senior-peer judgment (see project context for tone). When an answer is vague:
- A vague adjective without threshold ("fast", "secure", "simple", "robust") → push once: "Give me a number, or are we leaving this as a vibe?"
- A decision without rejected alternatives → push once: "What did you consider and reject?"
- An acceptance criterion that won't EARS-convert → push once: "Couldn't fit this to EARS — want to refine, or leave as prose?"
If the user says "leave it" or "vibe" or pushes back, accept and move on. The plan ships with annotated weak spots, not blocked on every weakness being resolved. The retrospective will catch what mattered.
**Never refuse to proceed.** The skill produces a plan with flagged weak spots, never a plan stuck waiting for a perfect answer.
### Hybrid ADR loop
When a decision surfaces in any answer (not just in dedicated decision questions), apply a short ADR pass *in-line*:
1. Note the decision
2. Ask what was considered and rejected (skip if already implicit in the answer)
3. Ask one-way-vs-two-way (skip if obvious)
4. Move on
End of Plan section, do one safety pass: "Decisions I caught: [list]. Any I missed?" This catches decisions the in-line detection missed without forcing a front-loaded enumeration.
### EARS conversion is visible and soft
When an acceptance criterion appears, attempt the EARS conversion *visibly*:
> "I read this as: WHEN user submits invalid input, THE SYSTEM SHALL log a structured error. Right?"
User confirms, corrects, or says "leave as prose." Un-converted criteria get flagged in the output (the flag is the signal for the retrospective). Don't silently background the conversion — the user wants to see what's happening.
### Iterate-vs-build phase detection
Listen for cues in phase descriptions: "polish," "design," "feel right," "iterate," "tone," "aesthetic," "UX." If detected, ask once:
> "This phase sounds iterate-shaped — done when you say done, not when a spec criterion is met. Right?"
Confirmed iterate-phases get tagged in the output so the agent treats them as converge-with-Travis loops, not finish-and-handoff. The acceptance criterion for iterate phases is allowed to be "Travis is happy" — don't force EARS on these.
### Visit Constitution twice
Open the section briefly: "Does this project have a constitution? If yes, state it. If no, is that intentional?" Loop the per-principle questions only if a constitution exists.
Close the section at the end of the interview with the cross-check: "Walk through each principle — does any element of Spec/Plan/Tasks violate it?" Constitution violations are critical; fix the plan, not the principle.
### Silent assembly, displayed at close
Build the plan artifact silently as the interview proceeds. Don't show mid-interview drafts unless the user asks ("show me what we have so far"). Progress signals — "skipped X", "captured Y" — are fine and expected.
At interview close, create the plan as a markdown artifact in chat (a viewable, copyable artifact, not a vault write).
### Don't write to vault
The vault is for committed, post-Lovebug artifacts. This skill stops at the chat artifact. The user handles the Lovebug pass and the vault write themselves — that's outside scope.
## End-of-interview behavior
When all sections are complete:
1. **Create the plan artifact** — markdown, in chat, copyable
2. **Capture telemetry in two questions:**
- "How many rounds of agent follow-up do you predict this plan needs?"
- "Ready to hand to Lovebug? Yes / not yet / no. If not yet or no — what's the one or two things missing?"
3. **Embed telemetry in the plan artifact itself** as a closing section (see "Output format" below)
4. **Stop.** No further orchestration. The user takes the artifact to Lovebug on their own.
The skill's own prediction (separate from the user's) can be offered if it seems useful: "My read is this needs 1-2 rounds. What's yours?" — it's optional, lightweight calibration data over time.
## Output format
The plan artifact is a markdown document with these top-level sections, in this order:
```markdown
# [Project title]
## Constitution
(Project-level principles, or "n/a — small project" if skipped)
## Spec
### Goal
### Problem
### Out of scope
### User journeys
### Requirements
(FR-001, FR-002, ... — each in EARS form where possible, marked
[PROSE] where EARS didn't fit)
### Success criteria
### Edge cases
## Plan
### Decisions
(Each decision: what we chose, what we rejected, one-way or two-way,
what it makes easier/harder)
### Data model
### Interfaces / contracts
### Deployment
### Tests
### NFRs (latency, threat model, observability — n/a where it applies)
### Phases (high-level — Phase N — name + scope)
## Tasks
### Phases (detailed — each phase lists which requirements it satisfies)
### Human-required handoffs
### Iterate-shaped phases (if any, tagged)
## Cross-cutting
### Codebase assumptions
### Unresolved questions
(Must-resolve-before-code / can-defer-and-tag-in-code / out-of-scope)
### Pre-mortem notes
## Interview telemetry
- Date: YYYY-MM-DD
- Skill predicted rounds: N
- Travis predicted rounds: N
- Go/no-go: yes | not yet | no
- Gaps named (if not yet/no): ___
- Un-EARS criteria: [list]
- Vibe answers (vague adjectives left un-quantified): [list]
```
Frontmatter is not required at this stage — the user adds vault-compatible frontmatter when committing to vault, per the existing markdown workflow.
## What this skill is not
- Not a vault writer (no writes to vault from the skill)
- Not a Lovebug orchestrator (the user handles that handoff manually)
- Not a code generator (the artifact is a plan, not code)
- Not a strict gate (the user can always proceed with weak spots, flagged)
- Not a framework adopter (this is not Spec Kit; we lifted question content only)
## Retrospective companion
A separate workflow handles retrospectives after the user has built the plan with Lovebug. This skill does *not* prompt for retrospectives. The user fires the retrospective separately when they have build data. Retrospective answers are captured as `session-notes` in the vault, linked to the project slug.
Retrospective questions to gather later (for reference only — not asked here):
- Actual rounds of agent follow-up
- Retrospective confidence (1–10)
- What surprised you
- What should the interview have asked but didn't
This skill's job ends when the chat artifact is delivered.
## On thoroughness vs. friction
The user values flexibility over rigor. If the interview feels like it's herding rather than helping, abbreviate. If a section's questions are clearly all answered, skip the section with one acknowledgment line. The number 42 is the *ceiling*, not the *target* — a typical session might ask 15–25 questions depending on what the user arrived with.
The 3-round agent-follow-up metric is the real measure. If the user starts hitting >3 rounds in retrospect, *that's* when to enforce more questions. Until then, lean lighter.

155
plan-interviewer/references/questions.md Normal file
View File

@ -0,0 +1,155 @@
# Question Set — Plan Interviewer
42 questions across 5 sections. Read this file at the start of every interview.
Lineage tags: **[SK]** Spec Kit · **[K]** Kiro/EARS · **[OS]** OpenSpec · **[BM]** BMAD · **[ADR]** Nygard/MADR · **[PRFAQ]** Amazon Working Backwards · **[RFC]** Rust RFC · **[PM]** Pre-mortem (Klein) · **[SDD]** SDD papers · **[CC]** Claude Code guidance · **[SOLO]** Solo-dev priority
---
## Spec — 12 questions
### Problem & motivation
1. In one sentence: what hurts today that this fixes? [PRFAQ]
2. What's the current workaround? There is always a current workaround. [PRFAQ]
3. Why now? What changed that makes this worth building this week and not six months ago? [RFC]
### Scope
4. List three things this project will deliberately NOT do. [SK gap-fill]
5. Is there anything in your draft that's a "maybe later" that should be moved to an explicit "NOT NOW" list? [SK]
### User stories & primary journey
6. Walk me through each primary user journey, step by step, in present tense, as if I were the user. [SK + PRFAQ]
### Acceptance criteria (applied per criterion)
7. For each acceptance criterion: rewrite it in EARS form — `WHEN [trigger] THE SYSTEM SHALL [response]`. If you can't, leave as prose and flag it. **Soft requirement.** [EARS]
8. For each user story, name the single observable behavior you could check in a browser/CLI to know it works. **Soft requirement — may bundle with #7's answer when natural.** [SK Independent Test]
### Edge cases
9. What happens on: empty state? Network/dependency failure? Concurrent edit? Action triggered twice quickly? Largest/smallest input outside the expected range? [K + SK consolidated]
### Success criteria
10. For each adjective in your spec — "fast", "simple", "responsive", "secure", "intuitive", "robust" — give me a number and a unit, or strike the adjective. [SK ambiguity pass]
11. What's the success metric for this project as a whole? If you can't tell whether it succeeded six weeks from now, your metric is wrong. [SK + PRFAQ]
### Hygiene scan (closes section)
12. Are there any `[NEEDS CLARIFICATION]`, TODO, ???, `<placeholder>` markers left? Read the spec out loud — does it mention any language, library, framework, file path, API endpoint, or database? Those are implementation leaks, move to Plan. [SK verbatim]
**Red flags during Spec:**
- "should" instead of MUST/SHALL
- Vague adjectives without thresholds
- Acceptance criteria written as test steps
- Tech stack in the spec
- No explicit non-goals
- Contradictory user stories
---
## Plan — 17 questions
### Decision interrogation (applied per non-trivial decision — hybrid in-line ADR loop)
1. What is the decision? State it as: "We will use X." [ADR]
2. What did you reject, and why? **Highest-leverage Plan question.** [ADR/MADR]
3. Is this a one-way door (hard to reverse — Postgres-vs-Mongo) or a two-way door (easy — UI library)? [Bezos framing]
4. What does this make easier? What does it make harder? [ADR — Nygard verbatim]
### Data model
5. List every entity. For each: fields, types, relationships, uniqueness constraints, indexes you anticipate. [SK data-model]
6. What's the migration path from current state to this schema? What's the rollback story if it turns out wrong? [OS brownfield-first]
### Interfaces / contracts
7. For each external interface (HTTP route, CLI command, MCP tool, library function): inputs, outputs, error shapes including status codes and retry semantics. [SK contracts + K]
8. What's the versioning story? What happens to existing callers when this changes? [RFC backwards-compat]
### Deployment
9. Where does this run, and how does it get from your editor to that environment? What secrets does it need and where are they stored? [SOLO consolidated]
10. What's the smallest reversible deploy unit? Can you ship Story 1 without Story 2? [SK independent-test]
### Tests
11. What's the testing posture for this project: TDD, test-after, or skip? State it explicitly — it changes task ordering. [SK + CC]
12. For each user story, name the test that would fail today and pass when it's done. [CC test-first][SK Independent Test]
### NFRs
13. What's the latency budget, throughput target, or concurrency limit if any of those matter for this project? (If none matter, say so explicitly.) [SK measurability] — **easy to skip with n/a**
14. Threat model in one paragraph: what's the attacker, what are they after, what's the trust boundary? What gets logged and where does the log go? [SDD + observability] — **easy to skip with n/a**
### Over-engineering scan
15. Is anything in this plan over-engineered for the scope? AI tends to over-build — flag anything that smells gold-plated. [SK verbatim warning][SOLO]
### Phasing
16. What's Phase 0 — the irreducible foundation everything else needs? What can be built in parallel vs. truly depends on what? [SK plan-template + SK [P]]
17. What's the first PR that delivers any user-visible value? [SOLO]
### End-of-Plan safety pass (always run)
After completing the Plan section, run a single safety pass:
> "Decisions I caught in this session: [list each one with its rejected alternatives]. Any I missed?"
This catches decisions the in-line ADR loop missed without forcing a front-loaded enumeration.
**Red flags during Plan:**
- Decision without rationale (no rejected alternatives)
- Consequences section only lists positives
- Schema in spec instead of plan
- No testing strategy stated
- No deploy/rollback story
- Contradiction with constitution (auto-CRITICAL)
---
## Tasks — 4 questions
1. Where are the natural decomposition points in this work? Those are your phases. [phasing]
2. Which phases require something only you can do — provision infrastructure, provide a secret, run a deploy from privileged hardware? Flag them so the agent knows where to pause and what's needed. [human-required blockers]
3. Walk the Spec's requirement list (FR-001, FR-002, ...). For each requirement, which phase satisfies it? Any orphans either direction — requirements without a phase, or phases without requirements? [exhaustive coverage check]
4. Are any phases iteration-shaped rather than build-shaped? Flag them so the agent treats them as converge-with-Travis loops rather than finish-and-handoff. Done is "Travis is happy", not a spec criterion. [iterate-vs-build — Travis-specific]
**Notes:**
- Tasks is the section most likely to be skipped on small projects. If the work is small enough that one ordered list of TODOs is overkill, skip the whole section with one acknowledgment.
- Question 3 requires the Spec requirements to be numbered (FR-001 etc). The skill should number them as it captures them in Spec.
---
## Constitution — 4 questions
Visit this section twice: once briefly at the open, once as a cross-check at the close of the whole interview.
### Open (Q1)
1. Does this project have a constitution — a short list of principles that apply across every feature, not just this one? If yes, state them. If no, is that intentional (small project) or should we draft a few before continuing?
### Per-principle interrogation (Q2-3, looped per principle if any exist)
2. State this principle in one sentence containing MUST or MUST NOT. Give me one concrete decision it would have changed in past work — if you can't, it's too vague to be a principle. [SK + BM]
3. How will the agent know mid-implementation whether it has violated this? Automatable check (lint/test/CI) or human-detectable only? [SDD Constitutional SDD]
### Close — cross-check (Q4, at end of whole interview)
4. Walk through each principle: does any element of the Spec, Plan, or Tasks violate it? Constitution violations are critical — fix the plan, not the principle. [SK constitution-alignment pass — auto-CRITICAL]
**Notes:**
- Most small projects don't need a constitution. Accept "no constitution, too small" and skip the section.
- Be ready for the answer to #3 sometimes being "no automatable check, just my judgment." That's fine — but knowing it's only judgment is itself useful.
---
## Cross-cutting — 5 questions (closes the interview)
### Codebase assumptions
1. What in the existing codebase is this plan assuming exists and works? What is it relying on but should not touch? Flag both — assumptions are the most common source of broken implementations. [OS brownfield + SOLO]
### Unresolved questions
2. What's still unresolved? List it explicitly — must-resolve-before-code vs. can-defer-and-tag-in-code vs. out-of-scope. [RFC verbatim distinction]
### Pre-mortem
3. Imagine it is 6 weeks from now. This project failed badly — not "ran late," actively went wrong. What happened? [PM — Klein verbatim framing]
4. Is there anything in this plan you secretly suspect is wrong but haven't surfaced because surfacing it would mean more work? Surface it now. [PM candor — Klein verbatim "things you wouldn't ordinarily mention"]
### Go/no-go (ends the interview)
5. Would you hand this plan to Lovebug right now and walk away? Yes / not yet / no. If not yet or no — what's the one or two things missing?
**Notes:**
- The pre-mortem (Q3-4) is the single highest-value question pair in the whole interview. Klein's research shows prospective hindsight produces 30% better failure identification, and the mechanism works for individuals, not just teams.
- The "secretly suspect is wrong" framing matters. Don't soften it to "any concerns?" — the wording does work.
---
## Total: 42 questions
Typical session asks 15–25 depending on what the user arrived with and how much is skipped. The 42 is the ceiling, not a target.