hstack 0.4.0 → 0.5.1

package/template/templates/discovery/forcing-questions.md

@@ -0,0 +1,76 @@
+---
+id: discovery-forcing-questions
+type: discovery-technique
+technique: forcing-questions
+applies-to: product-brief
+schema-version: 1
+---
+
+# Forcing-questions — technique script
+
+This is the prompt sequence `product-discovery` runs in Forcing-Questions mode. Use this when the engineer has a concept but it's vague or oversold — the technique probes claims and reframes the underlying pain. Pattern derived from YC-partner forcing questions and the Gstack approach.
+
+The agent's operating mode in this technique is **reframe-driven probing**: every claim the engineer makes triggers a reframe. The engineer's job is to defend the claim or accept the reframe. The brief converges only when the claims survive the probes.
+
+## Pre-flight check
+
+Before entering the script, the agent confirms:
+
+- The engineer has a concept they can state in one or two sentences.
+- The engineer is open to being wrong about their concept. The technique surfaces reframes that may invalidate the founder's first articulation; founders who can't tolerate that should pick Project-Brief mode instead.
+
+## Probe 1 — The 10-star reframe
+
+Ask: "What's the 10-star product hiding inside this request? What you described is 5-star; what's the 10-star version that solves the actual underlying pain?"
+
+The engineer's first answer is often a feature embellishment ("...with AI"). Re-ask: "That's a feature. What's the **underlying** pain — what does the user fail to do today that the 10-star product would make trivial?"
+
+The reframe sticks when the engineer names a pain that is one level deeper than the original concept. The brief's **Underlying Pain** section seeds from this answer.
+
+## Probe 2 — The smallest useful wedge
+
+Ask: "What's the smallest useful wedge? If you shipped one slice of the 10-star product and nothing else, what's the one slice that would still get a real user to pay?"
+
+The engineer's first answer is usually too large. Re-ask: "Cut it in half. What's left when you remove every feature that isn't load-bearing for the slice you just described?"
+
+The reframe sticks when the engineer names a wedge that can be built by one engineer in a quarter and that, alone, would justify a real user's payment. The brief's **Smallest Useful Wedge** section seeds from this answer.
+
+## Probe 3 — The named user
+
+Ask: "Who specifically pays for this? Name a real person — first name, role, company-size band, and the workflow this product enters on a Tuesday morning."
+
+The engineer's first answer is often a role abstraction ("Directors of CS"). Re-ask: "Pick one specific Director of CS you've talked to. What's her name, what's her company's name, and what does she do on a Tuesday morning that this product changes?"
+
+If the engineer cannot name a specific person, halt and surface: "The named-user constraint isn't met. We can either (a) park here and you go talk to three real users this week, or (b) acknowledge in the brief that this is anchored on a hypothetical user, which makes everything downstream a gamble." Founders sometimes choose (b); the brief records the choice in **Open Risks**.
+
+The brief's **Target User** section seeds from this answer.
+
+## Probe 4 — The falsification probe
+
+Ask: "What would you have to believe to be wrong about this concept? Name the belief and the evidence that would falsify it."
+
+The engineer's first answer is often "users won't like it" — too vague. Re-ask: "Be specific. What's a load-bearing assumption about the user, the market, or the technology that, if wrong, kills the product? And what experiment would tell you if it's wrong?"
+
+The reframe sticks when the engineer names a falsifiable belief plus an experiment that would resolve it within weeks. The brief's **Open Risks** section seeds from this answer.
+
+## Probe 5 — The scope-reduction question
+
+Ask: "If you had to ship in 8 weeks with one engineer, what would you cut? Walk me through the cut list."
+
+The engineer's cuts reveal what they think is load-bearing vs. embellishment. The brief's **Explicitly NOT** section seeds from the cut list — the things the engineer would cut are exactly the things v1 explicitly does NOT do.
+
+## Probe 6 — The reframe-staleness check
+
+After Probes 1–5, the agent surfaces: "The brief is converging on [X]. Your starting concept was [Y]. Any external documents (Notion pages, pitch deck, README) still naming [Y]? Those are now stale. Cleanup checklist:"
+
+The engineer either confirms the docs are stale and lists them for cleanup, or pushes back ("no, Y is still the framing") — in which case the agent re-runs Probe 1 to reconcile.
+
+## Synthesis
+
+After all six probes, the agent proposes a one-paragraph synthesis: "Here is what survived the probes. Concept: [refined X]. Underlying pain: [Probe 1 answer]. Smallest wedge: [Probe 2 answer]. Named user: [Probe 3 answer]. Falsification: [Probe 4 answer]." The engineer confirms or revises.
+
+On confirmation, the agent transitions to the **product-brief.md** template and walks the sections. The probe answers seed the corresponding brief sections; the Forcing-Prompt Answers section records the probes verbatim as evidence the technique ran.
+
+## Park-and-resume
+
+The agent surfaces a parking offer after each probe commits. If the engineer parks, the probe's output is persisted in `hstack/.session-state/<session-id>.yaml`. Resume picks up at the next probe.

package/template/templates/discovery/project-brief.md

@@ -0,0 +1,53 @@
+---
+id: discovery-project-brief
+type: discovery-technique
+technique: project-brief
+applies-to: product-brief
+schema-version: 1
+---
+
+# Project-brief — technique script
+
+This is the prompt sequence `product-discovery` runs in Project-Brief mode. Use this when the engineer is already concrete about the product and just needs structure to land the brief artifact. This is the **lightest-touch** technique — collaborative, structured, no heavy reframes — but the three required forcing prompts still fire.
+
+The agent's operating mode in this technique is **structured walk**: the engineer's existing thinking is the proposal layer; the agent prompts section by section, confirms or revises, lands the brief.
+
+## Pre-flight check
+
+Before entering the script, the agent confirms:
+
+- The engineer can state the concept in two or three sentences without hedging.
+- The engineer can name a specific real user (not a role abstraction).
+- The engineer can name a concrete success metric.
+
+If any of the three fails the concreteness floor, the agent halts and suggests switching to Forcing-Questions mode — the engineer's thinking is too vague for Project-Brief mode, which assumes concreteness.
+
+## Section walk
+
+The agent walks `product-brief.md` section by section. For each section, the agent asks one open question, accepts the engineer's answer, surfaces one clarifying re-ask if the answer is vague, then commits the section.
+
+1. **Underlying Pain** — "Describe what the user struggles with today, in concrete terms. A Tuesday-morning workflow vignette is the unit of clarity."
+2. **Target User** — "Name a specific real user. First name, role, company-size band, the tools they use, the workflow this product enters."
+3. **Value Proposition** — "What outcome does this product deliver to the named user? Outcome, not features."
+4. **Smallest Useful Wedge** — "What's the minimum shippable surface that delivers real value? Would the named user still pay for the wedge alone?"
+5. **Success Criteria** — "What measurable, time-bound outcome tells you v1 worked? Concrete number, concrete window."
+6. **Explicitly NOT** — "What is this product NOT? Two bullets minimum. What population it does NOT serve, what workflows it does NOT enter, what features it does NOT include."
+7. **Open Risks** — "What could make this product fail? Name at least one belief that, if wrong, kills the product."
+
+## Required forcing prompts
+
+Even in this lightest-touch mode, the three required forcing prompts MUST run before the brief can land. They run after the section walk completes:
+
+- "Who specifically pays for this?" — re-prompt the engineer to defend the Target User against the buyer question. The Target User and the buyer may be different (Maya the Director of CS uses it; her CFO pays for it). Both must be named.
+- "What's the smallest useful wedge?" — re-prompt the engineer to defend the wedge against the "would the user pay for the wedge alone?" question. Yes required.
+- "What would you have to believe to be wrong about this?" — re-prompt for a falsifiable belief + experiment to resolve it. Names the load-bearing risk.
+
+These three answers are logged in the brief's **Forcing-Prompt Answers** section as evidence the probes ran. The engineer cannot skip them; the technique downgrades to Forcing-Questions mode mid-session if the engineer refuses any of the three.
+
+## Synthesis
+
+There is no explicit synthesis step in Project-Brief mode — the section walk IS the synthesis. The brief lands at `status: current` when the last section commits and the three forcing prompts are answered.
+
+## Park-and-resume
+
+The agent surfaces a parking offer after each section commits. If the engineer parks, the section's output is on disk and `hstack/.session-state/<session-id>.yaml` records the next-section pointer. Resume picks up at the next section.

package/template/templates/product-brief.md

@@ -0,0 +1,56 @@
+---
+id: product-brief
+type: product-brief
+status: draft                          # draft | current | needs-refresh | archived
+owner: <git-handle>
+technique-used: <brainstorm | forcing-questions | project-brief>
+derived-from: []                       # always empty — product-brief is Phase 1, no upstream
+downstream: [vision, mvp-scope, personas, glossary]
+created: <YYYY-MM-DD>
+updated: <YYYY-MM-DD>
+schema-version: 1
+---
+
+## Underlying Pain
+
+_What the user actually struggles with on a Tuesday morning, in concrete terms. Not "users want X" — "this specific person spends 20 minutes doing Y and misses Z." One paragraph, 4–8 sentences. The forcing-prompt reframes should have moved this away from the founder's first articulation; the result lands here._
+
+## Target User
+
+_A named, specific user (not "users", not "customers") with a workday vignette. Includes role, company-size band, tools they use today, the workflow this product enters. If multiple personas matter for v1, name them all — but each must pass the concreteness floor._
+
+## Value Proposition
+
+_What this product delivers to the named user, in their language. One paragraph. Distinct from features — this is the outcome they buy._
+
+## Smallest Useful Wedge
+
+_The minimum shippable surface that delivers real value to the named user. Forcing-prompt answer: "Would the named user still pay for this if you shipped only the wedge and nothing else?" Yes required; if no, the wedge is too large or the user is wrong._
+
+## Success Criteria
+
+_Concrete, measurable, time-bound. "Maya saves 10 minutes per QBR prep within 4 weeks of activation" not "users love it." At least one criterion; more is better._
+
+## Explicitly NOT
+
+_Two-bullet minimum. The boundaries of the product. What this is NOT, what it does NOT do, what populations it does NOT serve. Required, never optional — over-broad scoping is the #1 product failure mode._
+
+-
+-
+
+## Open Risks
+
+_The things that could make this product fail. The forcing-prompt "What would you have to believe to be wrong about this?" answer lands here. At least one risk; more is better._
+
+## Forcing-Prompt Answers
+
+_Evidence that the three required reframes ran. Logged inline as confirmation the probes were not skipped._
+
+**Who specifically pays for this?**
+_The named user / buyer plus the rationale ("Director of CS, because retention is their KPI")._
+
+**What's the smallest useful wedge?**
+_The wedge plus the rationale ("Change-awareness alone, because the rest of the workflow is downstream of it")._
+
+**What would you have to believe to be wrong about this?**
+_The belief plus the falsifiability angle ("That CS reps will trust LLM-generated summaries — wrong if they require human-curated context")._