sam/pi-config

Fork 0

Files

Sam Rolfe 31b4110c87 Add 5 pi extensions: pi-subagents, pi-crew, rpiv-pi, pi-interactive-shell, pi-intercom

2026-05-08 15:59:25 +10:00

19 KiB

Raw Permalink Blame History

name, description, argument-hint

name

description

argument-hint

discover

Interview the developer one question at a time to extract feature intent and requirements, then synthesize into a Feature Requirements Document at thoughts/shared/discover/. The first question is intent-only and runs before any codebase probe; subsequent questions ground in evidence the probe surfaces. Use as the canonical entry point of the pipeline before research, or to stress-test a feature idea before codebase discovery. The FRD's Decisions block is consumed by `research` and propagates through Developer Context into `design`.

free-text feature description | existing artifact path

Discover

You are tasked with extracting feature intent and requirements through a one-question-at-a-time interview, then writing a Feature Requirements Document (FRD) that downstream skills consume. Two principles shape the flow: (1) intent before agents — the foundational intent question runs before any probe, so stated intent shapes the probe scope; (2) lazy + confirm — build the decision tree one layer at a time, and surface evidence-based pre-resolutions for confirmation rather than silently recording them.

How it works:

Read input (free-text or artifact path) (Step 1)
Foundational intent question — open, no recommendation, no file:line (Step 2)
Lightweight codebase probe shaped by stated intent (Step 3)
Build root + immediate children, batch-confirm pre-resolutions (Step 4)
Interview loop — tiered questions, lazy expansion, re-queue cross-cutting answers (Step 5)
Synthesize answers into FRD sections (Step 6)
Write artifact, present, chain to research (Step 7)

The final artifact is research-compatible — its Decisions block is translated into research's Developer Context and inherited by design.

Step 1: Input Handling

Input: $ARGUMENTS

No argument provided:

I'll capture feature intent into an FRD. Provide one of:

`/skill:discover [free-text feature description]`     — fresh interview, write a new FRD
`/skill:discover [existing artifact path]`            — refine an existing FRD/ticket/doc via fresh interview

Then wait for input.

Detect input shape — parse $ARGUMENTS:
- If the argument is an existing file path (resolves to a readable .md under thoughts/, or any path the user mentions for refinement context), read it FULLY using the Read tool WITHOUT limit/offset. Treat its content as baseline context — the interview surfaces gaps, missing requirements, and unstated assumptions relative to what's already documented.
- Otherwise → fresh-feature mode: the entire argument is the free-text feature description.
Read any other files mentioned in the prompt (tickets, docs, related artifacts, explicit path:line references) FULLY before proceeding.

No agent dispatch in Step 1. Only Read on user-named paths. Agent grounding starts in Step 3, after stated intent has shaped the probe scope.

Each invocation always writes a NEW timestamp-distinct artifact (Step 7) — there is no in-place stress-test append mode. To iterate on a prior FRD, either re-invoke discover (produces a fresh artifact) or manually Edit the prior artifact.

Step 2: Foundational Intent Question

Before any codebase probe, ask the foundational intent question. This is purely conversational — no agents, no recommendation, no file:line citations.

Ask one open-ended intent question via ask_user_question:
- Frame: "What problem are you solving and who hits it?" / "What does success look like for the person experiencing this today?" — phrase it for the specific feature.
- No (Recommended) option. The developer should generate the framing, not pick from a proposal.
- No file:line citations — codebase has nothing to say about intent.
- Options should be open shapes (e.g., "End user / maintainer / operator / Other") that route the answer, not solution shapes.
- Always offer "Other" so the developer can free-text the real framing.
Capture the answer in the developer's own words. This text feeds into the FRD's Problem & Intent section verbatim — do not paraphrase into agent prose.
Probe-readiness check: does the stated intent support a narrow probe slice (one component, one seam)? If yes → proceed to Step 3. If no (answer is too vague, e.g., "I dunno, feels slow"), ask one more intent question to sharpen scope, then re-check. Step 2 ends on probe-readiness, not at fixed N=1. Cap: 3 intent questions before falling through to Step 3 with whatever scope you have.

Step 3: Lightweight Codebase Probe (parallel agents, intent-shaped)

Goal: ground the upcoming interview in concrete codebase evidence, with the probe slice shaped by the developer's stated intent from Step 2 — not by raw $ARGUMENTS.

Pick the agent set. Dispatch codebase-locator, codebase-analyzer, or both — nothing else. Cap: 2 agents per Step 3 invocation.
Spawn the chosen agent(s) in parallel using the Agent tool. Draft each prompt yourself from the developer's stated intent — keep the slice narrow (one component, one seam) and avoid breadth phrasing like "everything related to X". Shape per call:
```
Agent({
  subagent_type: "codebase-locator",   // or "codebase-analyzer"
  description: "<3-5 word task>",
  prompt: "<your narrow-slice prompt, scoped to stated intent>"
})
```
The agent description on each subagent is the contract for what it expects in the prompt body.
Wait for ALL agents to complete before proceeding to Step 4.
Read any clearly-relevant files surfaced by the agents (≤5 files in main context, files <300 lines fully, larger files first 150 lines). Carry the agent reports and these files into Step 4 as evidence.
Empty results are not fatal. If the probe returns thin/empty results (greenfield, no precedent), record "no codebase precedent" as evidence — scope interview questions still work (they don't need file:line), and shape questions will shift to ungrounded "pick A or B by convention" mode.

Step 4: Lazy Tree Setup + Pre-Resolution Confirmation

Synthesize the next layer of questions internally before asking anything. Lazy expansion — build only root + immediate children at this stage, not the full tree. Each subsequent layer is built after its parent resolves.

Build root + immediate children:
- Root — the developer's already-stated problem from Step 2.
- Immediate children — the foundational unresolved branches: Goals/Non-Goals · Functional Requirements · Non-Functional Requirements (perf/security/UX/reliability) · Constraints · Acceptance Criteria · Recommended Approach.
- Order branches by dependency (root → goals → constraints → solution shape → details). This order drives the interview, not the FRD section order — Step 6 redistributes answers into FRD sections.
Mark evidence-based pre-resolutions from Step 3 with file:line citations. Do NOT silently record them as Decisions yet.
Batch-confirm pre-resolutions in a single ask_user_question call before entering the interview loop. Frame each as: "From the probe I inferred — <observed behavior> (file:line). Keep this for the feature, or change it as part of the work?" The developer's confirm/correct is the actual Decision.
- Confirm → record as Decision, rationale evidence: file:line + confirmed.
- Correct → flip the Decision direction, schedule a Correction probe at Step 5 (≤1 additional agent on the new seam).
The lazy tree stays internal — do NOT present the tree to the developer unless asked.

Step 5: Interview Loop

Walk the lazy tree depth-first, parent before child. Expand the next layer (build a node's children) only after the node resolves. For each unresolved node:

Classify the question by tier:
- intent — already done in Step 2. Do not re-ask intent in this loop.
- scope (goals · non-goals · functional reqs · non-functional reqs · constraints) — recommendation grounded in stated intent. file:line citations only when an option references existing code; otherwise state "no codebase precedent" in the option description.
- shape (architectural choice — which seam, which pattern, which integration point) — recommendation with file:line citations required on every option that references existing code. Mirrors the packages/rpiv-pi/skills/research/SKILL.md:103-142 checkpoint pattern. If no precedent exists, switch to ungrounded mode and label options as "convention A / convention B" with explicit "no codebase precedent".
- detail (acceptance criteria · routine sub-decisions inside any branch) — batchable when 2-4 sibling leaves are independent.
Recommended answer (scope / shape / detail): derive from intent + Step 3 evidence + project conventions. Every non-intent question carries a recommendation labeled (Recommended).
Ask via ask_user_question. Lead with the recommended option. The "Other" option is automatic and handles open-ended answers.
Critical rules:
- Ask ONE question at a time. Wait for the answer before asking the next.
- If a new evidence-based node surfaces mid-loop, batch-confirm it the way Step 4 does — never silently auto-record.
Classify each response:
- Decision ("yes, that recommendation is right" / "use option B"): Record in Decisions. Resolve the node. Expand its children if any. Continue.
- Correction ("no, the real intent is X" / "you missed Y"): Re-run targeted Step 3 grep on the new area; spawn at most 1 additional narrow agent per correction event if the correction reveals a seam not yet probed. Adjust the affected subtree. Re-ask any descendants that depend on the corrected node.
- Scope adjustment ("skip the UI part" / "include retries"): Update the tree — prune pruned branches, add new branches if needed. Record in Decisions.
- Cross-cutting answer ("we also need audit / rate limiting / X" — affects multiple branches): Mark the new node as cross-cutting and re-queue it. When the walk reaches each affected parent (functional / non-functional / constraints), the cross-cutter fires under that parent's context. Same node, multiple parents resolved sequentially.
- Defer ("not sure, leave for later"): Add to Open Questions. Resolve the node by deferral. Continue.
Batching: When 2-4 sibling detail leaves are independent (answers don't depend on each other), you MAY batch them in a single ask_user_question call. Keep dependent questions sequential. Do not batch scope or shape questions.
Termination — depth check, not bucket-fill: stop the loop when:
- (a) every branch has a Decision or a Deferral, AND
- (b) the developer's own words appear in Problem/Goals (not paraphrased agent prose), AND
- (c) no Decision is Recommendation accepted without at least one Rationale clause beyond agreed.
Do not invent questions to pad the interview. Do NOT ask a final "looks good / want to adjust" rubber-stamp question — chain forward to research is automatic at Step 7.

Total agent budget across the skill: 2 (Step 3 initial probe) + N×1 (Step 5 corrections, typically 0-2) = 2-4 agent dispatches per FRD.

Step 6: Synthesize FRD Body

Read templates/frd.md (relative to this skill folder) at runtime to confirm the section list and frontmatter shape — do not inline it from memory.

Compile interview output into the FRD. The interview's logical order (problem → goals → constraints → solution → details) is decoupled from the FRD's section order — redistribute answers into the template buckets here:

Summary — 2-3 sentences capturing the settled feature concept.
Problem & Intent — the developer's framing from Step 2, in their own words. Verbatim where possible.
Goals / Non-Goals — explicit in/out lists from the interview.
Functional Requirements — numbered, each independently testable.
Non-Functional Requirements — perf, security, UX, accessibility, reliability constraints.
Constraints & Assumptions — environmental, technical, schedule, organizational.
Acceptance Criteria — observable pass conditions a reviewer can check.
Recommended Approach — 1-2 sentences naming the architectural shape implied by the decisions (e.g., "new command in packages/rpiv-pi/extensions/, output to stdout, no persistence"). This text is what research passes to scope-tracer as the topic for breadth grounding.
Decisions — full Q/A log per decision: ### [title] + **Question**: (text as asked, or "Pre-resolved from codebase evidence — confirmed in Step 4") + **Recommended**: (or "n/a — intent question") + **Chosen**: (developer's pick or evidence-derived answer) + **Rationale**: (1 line — why, or evidence: path/to/file.ext:line + confirmed for codebase-derived). This block is the inheritance hook into research's Developer Context.
Open Questions — only items the developer explicitly deferred.
References — input files, mentioned tickets, related artifacts.

Step 7: Write Artifact, Present, Chain

Determine metadata:
- Filename: thoughts/shared/discover/<YYYY-MM-DD_HH-MM-SS>_<topic>.md
  - Topic: kebab-case slug derived from the settled feature concept (lowercase, hyphens for spaces, strip special chars).
  - Timestamp guarantees uniqueness across invocations — no slug-collision check.
- Repository name: from git root basename, or current directory basename if not a git repo.
- Use the git branch and commit from the git context injected at the start of the session (or run git branch --show-current / git rev-parse --short HEAD directly; fallbacks: no-branch / no-commit).
- Timestamp: run date +"%Y-%m-%dT%H:%M:%S%z" — raw for date: and last_updated:, first 19 chars (T→_, :→-) for filename slug.
- Interviewer: from the User in the injected git context (fallback: unknown).
Write the FRD using the Write tool. Frontmatter status: complete. All template sections present and filled. The directory thoughts/shared/discover/ is pre-scaffolded by session-hooks.ts — no mkdir -p needed in the skill.

Present and chain:

Intent captured to:
`thoughts/shared/discover/<YYYY-MM-DD_HH-MM-SS>_<topic>.md`

{N} requirements, {M} decisions, {K} open questions.

The FRD's Decisions block is translated into research's Developer Context and inherited by design.

---

💬 Follow-up: discover writes a fresh FRD per call — re-invoke `/skill:discover` to iterate (the prior FRD stays unchanged on disk).

**Next step:** `/skill:research thoughts/shared/discover/<YYYY-MM-DD_HH-MM-SS>_<topic>.md` — ground the intent in codebase reality.

> 🆕 Tip: start a fresh session with `/new` first — chained skills work best with a clean context window.

Step 8: Handle Follow-ups

Fresh artifact per call, no in-place append. Discover deliberately writes a NEW timestamp-distinct FRD on every invocation — there is no ## Follow-up append mode. The prior FRD stays unchanged on disk.
Iterate by re-invoking. Re-run /skill:discover [path-to-prior-FRD] (or /skill:discover <free-text>) to produce a fresh FRD informed by the prior one.
No rubber-stamp question. NEVER ask a final "looks good / want to adjust" question — chain forward to research is automatic at Step 7.
Manual edits are allowed. If the developer wants a one-off correction without re-running the full interview, they can Edit the FRD directly — the skill does not own follow-up surface area beyond fresh-artifact-per-call.

Important Notes

These reinforce the critical rules from the steps above — listed here so they don't get lost in step-body detail.

Always interview-first, intent-first: Never write the FRD without running the interview loop. The intent question (Step 2) always precedes any agent dispatch — let stated intent shape the probe, not the other way around.
Always one question at a time: Even with 2-4 batched independent detail leaves, that's still one ask_user_question call — wait for answers before asking the next round.
intent generates, scope/shape/detail reviews: Intent is the developer's framing — they generate it. Scope, shape, and detail are proposals — they review them. The "developer reviews a proposal" model does not apply at the intent layer.
file:line is tier-conditional: intent — never. scope — only when an option references existing code, otherwise label "no codebase precedent". shape — required on every option that references existing code; if no precedent exists, switch to ungrounded "convention A / convention B" mode. detail — same rule as scope.
Lazy tree, no full-tree pre-build: Build only root + immediate children in Step 4. Expand each node's children only after the node resolves. Premature full-tree construction biases the dialogue.
Pre-resolutions confirm, never silently record: Evidence-based nodes are batch-confirmed in Step 4 (or mid-loop if newly surfaced). The developer's confirm/correct is the actual Decision.
Cross-cutting answers re-queue, don't duplicate or drop: When an answer affects multiple branches, mark the node cross-cutting and fire it under each affected parent during the walk.
Interview order ≠ FRD section order: Walk the tree in dependency order (problem → goals → constraints → solution → details). Step 6 redistributes answers into FRD sections.
Light fan-out only: Step 3 ≤2 agents (codebase-locator + optionally codebase-analyzer). Step 5 Corrections ≤1 additional agent per correction event. Breadth discovery (scope-tracer, broad sweeps, integration-scanner) belongs to research — chain forward instead of expanding scope here.
Never write or edit source files: This skill produces an artifact only. Source-file changes are implement's job, far downstream.
Fresh artifact every invocation: Each /skill:discover call writes a NEW timestamp-distinct file. To iterate on a prior FRD, re-invoke or manually Edit the prior file.
Critical ordering — follow the numbered steps exactly:
- ALWAYS read mentioned files before any agent dispatch (Step 1 → Step 2)
- ALWAYS ask the intent question before probing (Step 2 → Step 3)
- ALWAYS shape the probe by stated intent, not raw $ARGUMENTS (Step 3)
- ALWAYS batch-confirm pre-resolutions instead of silent auto-record (Step 4)
- ALWAYS expand the tree lazily during the interview (Step 5)
- ALWAYS re-queue cross-cutting answers under each affected parent (Step 5)
- ALWAYS terminate on depth signal, not bucket-fill (Step 5)
- ALWAYS synthesize from the interview log, never from memory of the conversation (Step 6)
- NEVER skip the developer-facing interview — it's the entire point of this skill
- NEVER ask a final "looks good / want to adjust" rubber-stamp question (anti-pattern per a93e591)
- NEVER dispatch agents before Step 2's intent question is answered

19 KiB Raw Permalink Blame History Unescape Escape