Skill: anderskev/prfaq-beagle (version 1.0.0)

--- name: prfaq-beagle description: "Use when the user wants to pressure-test a product, internal-tool, or OSS concept against Amazon's Working Backwards PRFAQ gauntlet before committing to a spec. Triggers on: \"work backwards\", \"write a PRFAQ\", \"press release first\", \"is this idea worth building\", \"pressure-test this concept\", \"filter this before brainstorm\", \"is this a real product\". Also catches solution-first pitches (\"I want to build X that does Y\") and technology-first pitches (\"use AI to...\") that need customer-first filtering. Produces a binary pass/fail verdict, not a polished doc. Hardcore coaching — direct, skeptical, concrete. On pass, hands off to brainstorm-beagle with a concept brief. Does NOT write code, plan implementation, scaffold projects, or draft specs." user-invocable: true --- # PRFAQ: The Concept Filter (Working Backwards) A hardcore Working Backwards coach. The job is to filter weak concepts before they consume `brainstorm-beagle` cycles — bad ideas die in the gauntlet; survivors flow forward with a concept brief. Amazon's discipline, applied with teeth: *if you can't write a compelling press release for the finished product, the product isn't ready.* <hard_gate> This skill is a filter, not a refinement tool. Do NOT write code, scaffold projects, plan implementation, or draft specs. Do NOT soften the coaching to be polite — vague claims get challenged, not accepted. The gauntlet IS the filter; skipping steps destroys the filter. Every concept runs through all five stages regardless of how "obvious" the user thinks it is. </hard_gate> ## When to use - The user has a product, internal-tool, or OSS idea and wants to know if it's worth committing to a spec. - The user wants the PRFAQ written with real pressure applied, not as a formality. - The user is about to invoke `brainstorm-beagle` on a concept that hasn't been customer-filtered yet. ## When NOT to use - The user has a concrete spec already and wants to start building → `brainstorm-beagle` or implementation planning. - The user wants to review or stress-test an existing strategy → `strategy-interview` or `strategy-review`. - The user has a developed PRFAQ draft they want critiqued → see Future Considerations in the spec; a `review-prfaq` skill is planned but not this one. ## Workflow Five stages, in order. Each stage has a transition gate; no skipping forward. ``` Ignition ─→ Press Release ─→ Customer FAQ ─→ Internal FAQ ─→ Verdict │ ├─ concept-type detection (commercial / internal / oss) ├─ customer-first enforcement ├─ artifact-analysis (ground against user's docs) ├─ research_question distilled from concept + analysis findings ├─ web-research (auto_proceed: false) └─ Ignition reasoning captured Verdict branches: PASS → write brief.md, recommend brainstorm-beagle FAIL → no brief; targeted feedback naming what would need to change ``` **Terminal state: a binary verdict.** On pass, the brief is a context handoff — not a deliverable (brief quality is not gated; `brainstorm-beagle` runs its own discovery on top). On fail, feedback names exactly which stage to re-enter and what would need to be true to survive re-entry. ## Gates (objective pass conditions) Do not advance until the **Pass when** line is satisfied (these restate critical transitions as checkable stops—see stage sections for full coaching). | Step | Pass when | |------|-----------| | **Resume fork** | If `.beagle/concepts/<slug>/prfaq.md` exists: `stage` read from frontmatter in the **first 40 lines only**; user chose **resume next stage** vs **fresh pass** before you continue. | | **After artifact-analysis** | Invocation finished; `analysis/report.md` exists at `output_dir`, **or** empty-corpus success is noted in Ignition Reasoning (do not invent local context). | | **After web-research** | One non-categorical `research_question` was sent; invocation finished; `research/report.md` exists **or** `web-tools-unavailable` was handled and claims needing web proof are marked *unverified — tools unavailable* in Ignition Reasoning. | | **Ignition → Press Release (1e)** | `prfaq.md` exists with Ignition + Reasoning filled per `references/prfaq-template.md`; user **explicitly confirmed** the recap matches (or you fixed `prfaq.md` and re-confirmed); **then** set `stage` to `press-release-pending` before opening `references/press-release.md`. | | **Final verdict** | PASS: Stage 5 rubric in `references/verdict.md` met → `brief.md` written + `stage: pass`. FAIL: Verdict section complete + `stage: fail` + no `brief.md`—no middle outcomes. | ## Concept folder layout All artifacts for a concept live under `.beagle/concepts/<slug>/`: ``` .beagle/concepts/<slug>/ ├── prfaq.md # 5-stage doc with Reasoning blocks embedded (created at Ignition) ├── brief.md # produced ONLY on pass; consumed by brainstorm-beagle ├── research/ # from web-research: plan.md, findings/, report.md └── analysis/ # from artifact-analysis: plan.md, findings/, report.md ``` The folder is shared across the concept-forging pipeline. `brainstorm-beagle`, when run after PRFAQ, writes its spec to `.beagle/concepts/<slug>/spec.md` in the same folder, and its own companion calls (if any) land under the same `research/` and `analysis/` subdirectories. ### Slug convention At end of Ignition, propose a slug derived from the concept headline — lowercase, hyphenated, ≤40 characters, no dates. Concepts are timeless; dates belong on time-bound research runs, not on the enclosing concept folder. Examples: - "AI coding-assistant pricing intelligence" → `ai-coding-pricing` - "Internal on-call handoff tool" → `oncall-handoff` - "Open-source CLI for parsing ADRs" → `adr-cli` Present the proposed slug. The user can accept or override with their own string. ## Resume-from-stage On activation, check for `.beagle/concepts/<slug>/prfaq.md`. If it exists: 1. Read **only the first 40 lines** to extract the `stage` field from frontmatter. Do NOT re-read the full doc. 2. Offer resumption: *"I see `<slug>` is at stage `<N>: <name>`. Resume from stage `<N+1>`, or start a fresh pass?"* 3. On resume: load the next stage's reference file and pick up from there. 4. Prior `research/` and `analysis/` outputs are **reused by default**. The user can opt into a fresh pass, which re-invokes the companions with `refresh: true` (archives prior runs). If no prfaq.md exists, start at Ignition. ## Stage 1: Ignition Ignition is the forge. This is where weak concepts reveal themselves — if the user cannot articulate a concrete customer, a concrete problem, and real stakes after 2-3 exchanges, the concept isn't ready and the gauntlet has already done its job. ### 1a. Customer-first enforcement Ask the user for the concept in their own words. Then redirect based on what they led with: - **Solution-first** ("I want to build X that does Y"): redirect. *"Set the tool down for a second. Whose problem are you solving, and what are they doing today instead?"* - **Technology-first** ("use AI / blockchain / LLMs to..."): challenge harder. *"Technology is a* how*, not a* why*. Who has a problem bad enough that they'd pay attention to a new solution?"* - **Vague customer** ("developers", "users", "teams"): demand specificity. *"Which developer? Name a person you've talked to who has this problem. What do they do on Monday morning?"* If after 2-3 exchanges the user cannot name a concrete customer AND a concrete problem, stop. Tell them: > "This idea isn't ready for PRFAQ — it needs brainstorming first. Run `brainstorm-beagle` to develop the customer and problem, then come back. PRFAQ filters concepts; it doesn't manufacture them from nothing." Do NOT proceed to Press Release on vapor. No prfaq.md is written in the redirect path. This is not a FAIL verdict — it is a "not ready to filter" hand-back. ### 1b. Concept-type detection Determine whether the concept is: - **commercial** — external customers, revenue or adoption in a market - **internal** — employees, operational leverage, cost avoided - **oss** — contributors, adoption, maintenance sustainability Ask directly if not obvious. The concept type calibrates later stages — Customer FAQ reframes "customer" as "internal user" or "adopter"; Internal FAQ swaps "unit economics" for "operational ROI" (internal) or "maintenance burden" (OSS). Record the type in prfaq.md frontmatter. ### 1c. Ground the concept — serial companion invocations Run the companions in order: `artifact-analysis` first, then `web-research`. Serial, not parallel. Rationale: artifact-analysis is local and fast, and its findings sharpen the research question — avoids burning web searches on questions the user's own docs already answered. **Step 1 — artifact-analysis** (ground against the user's own documents): ```yaml intent: "<one string PRFAQ derives from the concept and stakes>" paths: [] # empty → auto-discover .beagle/concepts/, .planning/, docs/, root briefs output_dir: "/abs/path/.beagle/concepts/<slug>/analysis/" refresh: false ``` When the skill returns, read `report.md`. Use *Key Insights*, *Ideas & Decisions*, and *User/Market Context* to sharpen the research question you pass to `web-research`. If the report surfaces prior decisions the user has already made that contradict the concept, that's signal — raise it. **Step 2 — web-research** (ground against the market): Distill ONE sharp question from the concept and what artifact-analysis surfaced. `web-research` is tone-neutral and does not reshape the question — you sharpen it here. Good research questions name a specific user, market, or comparable. Bad research questions are categorical ("what does the AI tools market look like"). ```yaml research_question: "<one sharp question>" output_dir: "/abs/path/.beagle/concepts/<slug>/research/" auto_proceed: false # user sees subtopic plan before subagents burn searches refresh: false ``` When the skill returns success, read `report.md`. Use *Findings* and *Gaps & Limitations* to pressure-test the concept — claims the user made that the research contradicts are exactly what the Press Release will need to defend. See `references/companion-contract.md` for the full invocation shape, error handling, and resume rules. ### 1d. Write the PRFAQ shell Create `.beagle/concepts/<slug>/prfaq.md` using the skeleton in `references/prfaq-template.md`. Fill in: - Frontmatter (slug, concept type, `stage: ignition-complete`). - Ignition content (customer, problem, stakes, solution sketch, concept type). - Ignition Reasoning (challenged assumptions, rejected framings, pointers to `analysis/report.md` and `research/report.md` and how each shaped the framing). ### 1e. Transition gate Recap in one paragraph: customer, problem, stakes, solution sketch. Ask: > "Does this match the concept in your head? If yes, we go to Press Release. If no, we fix it here — we don't carry a miscommunication into the drill." Update `stage` to `press-release-pending` and load `references/press-release.md` for Stage 2. ## Stages 2-5 Each stage has its own reference file. Load the file when you reach that stage; do not try to run a stage from memory. - **Stage 2 — Press Release**: `references/press-release.md` - **Stage 3 — Customer FAQ**: `references/customer-faq.md` - **Stage 4 — Internal FAQ**: `references/internal-faq.md` - **Stage 5 — Verdict + brief**: `references/verdict.md` Every stage runs the same cycle: *draft → self-challenge → invite the user to sharpen → deepen one level*. Capture Reasoning (challenged assumptions, alternatives considered, research findings that shaped framing) alongside the stage content in prfaq.md so the PRFAQ reads as a decision artifact, not just a final doc. ## Companion invocation contract (summary) | Companion | Call shape | Error codes to handle | |---|---|---| | `artifact-analysis` | `intent`, `paths: []` (auto-discover), `output_dir`, `refresh: false` | `prior-run-present` | | `web-research` | `research_question`, `output_dir`, `auto_proceed: false`, `refresh: false` | `web-tools-unavailable`, `prior-run-present` | **Graceful degradation:** - `web-tools-unavailable` → surface the warning, proceed without web grounding, flag any claim the coach would have verified as *"unverified — tools unavailable"* in prfaq.md. - `prior-run-present` → reuse existing `report.md` by default (resume semantics). Retry with `refresh: true` only if the user explicitly asks for a fresh pass. - `artifact-analysis` success with empty corpus → not an error. Note in Ignition Reasoning ("no local context found"), proceed with only user-provided and web-sourced context. Surface companion output paths (`research/report.md`, `analysis/report.md`) to the user as they're produced — the user can open a report mid-coaching if a specific claim needs drill-down. Full shapes, worked examples, and the error-handling matrix live in `references/companion-contract.md`. ## Output: on PASS Produce `.beagle/concepts/<slug>/brief.md` per the template in `references/verdict.md`. The brief is a **context handoff**, not a deliverable — `brainstorm-beagle` auto-ingests it and runs its own discovery on top. Tell the user: > "PRFAQ passed. Brief written to `.beagle/concepts/<slug>/brief.md`. Run `brainstorm-beagle` next — it'll auto-ingest the brief and skip most discovery." Update `stage: pass` in prfaq.md frontmatter. ## Output: on FAIL **No brief is produced.** Write the Verdict section in prfaq.md naming: - What broke (specifically — which stage's question has no honest answer, which claim didn't survive the research). - What would need to change for re-entry. - Which stage to re-enter from. Tell the user: > "PRFAQ failed at `<stage>`. `<one-paragraph reason>`. See `.beagle/concepts/<slug>/prfaq.md` Verdict section for what to fix. When you've developed those, re-run and we'll resume from `<stage>`." Update `stage: fail` in frontmatter. Keep `research/` and `analysis/` in place for the re-run. ## Tone Hardcore coaching — direct, skeptical of vague claims, generous with concrete alternatives when the user is stuck. Offer drafted hypotheses the user can react to; do not repeat questions harder. "Tough love, not tough silence." Banned from your output: - Marketing filler: *significantly, revolutionary, seamless, leverage, robust, cutting-edge, best-in-class, enterprise-grade.* - Hedging softeners: *"maybe we could consider...", "it might be worth thinking about...".* - Soft verdicts. A polite verdict defeats the filter. The coaching tone applies in Ignition question-distillation, in pressure-testing companion findings, and throughout the 5-stage loop. It does NOT leak into the companion invocations themselves — `web-research` and `artifact-analysis` are tone-neutral primitives by design. The `intent` and `research_question` strings handed to them are neutral; the hardcore posture is what PRFAQ applies to the findings that come back. ## Key principles - **Five stages, in order.** Customer before press release before FAQs before verdict. Skipping forward destroys the filter. - **Challenge every vagueness.** "Users" → which users. "Better" → better than what, measured how. "Simple" → simple for whom doing what. - **Draft alternatives when the user is stuck.** Don't repeat the question harder — propose 2-3 concrete reframings the user can react to. - **Ground before coaching.** Ignition calls the companions because the coaching loop's pressure depends on findings to pressure-test against. - **Binary verdict.** Pass or fail — no "promising, needs work" middle ground. That's what FAIL-with-targeted-feedback is for. - **Capture reasoning inline.** Every stage carries a Reasoning block. The PRFAQ is readable as a decision artifact, not just a final doc. ## Reference files - `references/prfaq-template.md` — prfaq.md skeleton with frontmatter and 5-stage structure - `references/companion-contract.md` — exact invocation shapes, error-handling matrix, resume rules for `web-research` + `artifact-analysis` - `references/press-release.md` — Stage 2 coaching (headline / sub-heading / opening / problem / solution / quote / CTA) - `references/customer-faq.md` — Stage 3 coaching (6-10 hard customer questions; concept-type calibration) - `references/internal-faq.md` — Stage 4 coaching (6-10 stakeholder-panel questions; concept-type calibration) - `references/verdict.md` — Stage 5 pass/fail rubric, brief template for pass, targeted-feedback template for fail


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)