@manhquy/flow-skill 0.1.0-rc.1

package/skills/flow/_templates/00-idea.md

@@ -0,0 +1,16 @@
+# Stage 00 — Idea
+
+## Gate — check ALL before `/flow next`
+- [ ] The pitch below is 3 sentences, no more
+- [ ] I can name at least ONE real person/group who has this pain (named below)
+- [ ] No FILL placeholders remain in this file
+
+## Pitch (3 sentences: who, pain, what you'd build)
+
+[FILL: sentence 1 — who has the problem]
+[FILL: sentence 2 — what the pain is, concretely]
+[FILL: sentence 3 — what you would build]
+
+## One real person/group with this pain
+
+[FILL: name a real person, community, or group you have actually seen express this pain]

package/skills/flow/_templates/00-inspect.md

@@ -0,0 +1,42 @@
+# Stage 00-inspect — Brownfield assessment (existing codebase)
+
+Run this BEFORE planning when the project ALREADY EXISTS. Goal: an honest current-state map so
+planning starts from reality, not a blank page. Fill every section from EVIDENCE (read the code),
+then check the gate. `/flow assess` seeds the auto-scan and validates this gate.
+
+## Gate — check ALL before planning
+- [ ] I detected the stack / build / test / run commands (from real files; listed below)
+- [ ] I mapped the main components/modules and entry points
+- [ ] I assessed current functionality state (works / partial / broken) with file evidence
+- [ ] I assessed UI/UX state vs the product's stated goals (or noted "no UI")
+- [ ] I listed the top risks / tech-debt / known issues
+- [ ] I noted the test + quality baseline (what is covered vs not)
+- [ ] A human reviewed this assessment (brownfield assessment is operator-gated)
+- [ ] No FILL placeholders remain in this file
+
+## Detected (auto-scan)
+[FILL: replace with the `/flow assess` auto-scan output — stack, CI, context files]
+
+## Ranked surfaces (auto-scan — read these first)
+The auto-scan ranks source files by how widely their symbols are referenced (highest-leverage
+code first). Start your functionality + risk assessment from the top of that list — the surfaces
+most of the codebase depends on are where a hidden cross-cutting risk (e.g. unscoped data access)
+is most likely to hide. [FILL: note which ranked surfaces you inspected + what you found.]
+
+## What this product is (from docs/specs/code, not guesses)
+[FILL: 2-3 sentences — the real product + who it's for + the core job]
+
+## Current functionality state (evidence)
+[FILL: per major feature — works / partial / stub / missing, each with file:line]
+
+## UI / UX state vs product goals
+[FILL: screens/flows present + gaps vs the stated goals; or "no UI"]
+
+## Risks / tech-debt / known issues
+[FILL: top items, ranked; cite where]
+
+## Test + quality baseline
+[FILL: what is tested vs not; how to run the suite; coverage if known]
+
+## Verdict
+[FILL: is the codebase healthy enough to build on? what must be fixed first?]

package/skills/flow/_templates/01-research.md

@@ -0,0 +1,59 @@
+# Stage 01 — Research (inspect first)
+
+Rule: INSPECT what already exists. Evidence required — links, quotes, screenshots.
+"I think there's nothing like this" without searching = gate fail.
+
+> Project type (`/flow project-type`, default `web`): items 2 and 4 below are written for a
+> **web / market-facing product**. For an **internal tool / cli / library / skill** (no public
+> market), use the non-web framing in each item — it is still real evidence (first-party
+> friction, who-benefits), NOT an excuse to skip. The semantic gate refuses a market product
+> that hides behind the soft framing.
+
+## Gate — check ALL before `/flow next`
+- [ ] I actually OPENED 3 existing tools/competitors (links below, with one honest note each)
+- [ ] **(web)** I found 3 REAL user complaints online, quoted, with source links — **OR (non-web/internal)** I named the concrete first-party friction / observed pain that justifies this
+- [ ] I wrote what competitors CHARGE (real prices) and who pays — **OR (non-web)** what people spend AROUND this problem today (time, a worse tool, manual work)
+- [ ] **(web)** I named the ONE channel my first 10 users come from (a place, not "social media") — **OR (non-web/internal)** I named who benefits and how they hear about it (release notes / team), and noted "no market channel" is NOT a kill signal for an internal tool
+- [ ] I wrote why those users would pick this over the status quo (one honest paragraph)
+- [ ] I wrote what is technically free vs hard for this idea
+- [ ] No FILL placeholders remain in this file
+
+## What exists already (3 — open them, don't guess)
+
+1. [FILL: name + link — what it does well / where it falls short]
+2. [FILL]
+3. [FILL]
+
+## What users say (web: 3 real complaints quoted+linked · non-web: real first-party friction)
+
+1. > [FILL: a real user complaint quoted, with a source link — OR, for an internal tool, a concrete observed friction/pain (who hit it, when)]
+2. > [FILL]
+3. > [FILL]
+
+## GTM & business reality
+
+Building is the cheap part now. Distribution and willingness-to-pay are where ideas die —
+research them BEFORE planning, not after shipping.
+
+### Who pays today, and how much (pricing reference points)
+
+- [FILL: competitor/status-quo → real price → who pays it (link). 2-3 rows. "It's free"
+  counts: then what do people pay AROUND the problem (time, staff, a bigger suite)?]
+
+### The first-10-users channel (web) · who-benefits (non-web/internal)
+
+[FILL: WEB — the specific place/community/list where the first 10 users come from, and why
+you can reach them there (a named Zalo/FB group, a building, a forum, YOUR audience — not
+"social media" / "word of mouth"); if you cannot name one, that is a KILL signal at scope.
+NON-WEB/INTERNAL — who benefits (which users/teams) and how they learn about it (release
+notes, internal docs); "no market channel" is expected and is NOT a kill signal here.]
+
+### Why switch (vs the status quo)
+
+[FILL: one honest paragraph — what makes the named users move off what they do today?
+Cheaper / faster / local-fit / removes a named pain? "Mine is better" is not an answer.]
+
+## Technically free vs hard
+
+- Free (solved by libraries/platforms): [FILL]
+- Hard (custom work, real risk): [FILL]

package/skills/flow/_templates/02-scope.md

@@ -0,0 +1,71 @@
+# Stage 02 — Scope (go/no-go)
+
+Scope = features chosen by IMPACT × COST, inside your time budget.
+KILL here is cheap and smart. Killing a weak idea at this gate is a SUCCESS outcome.
+
+## Impact rubric (business value — score BEFORE looking at cost)
+
+| Impact | Meaning |
+|---|---|
+| H | moves money or the core promise: gets users in (acquisition), gets them paying (revenue), or delivers the one job they came for |
+| M | keeps users / saves real time weekly (retention, operations) |
+| L | nice-to-have; nobody would pay for or switch over it |
+
+Decision matrix: **H-impact features justify B/C cost** (via the C-paths below).
+**L-impact features must be grade A or they're cut** — and even grade-A L-features are
+cut when the budget is tight. The classic failure is a v1 full of A-grade L-impact
+features: cheap to build, worthless to sell.
+
+## AI coding grade rubric
+
+| Grade | Meaning | Examples |
+|---|---|---|
+| A | cheap for AI | CRUD, forms, dashboards, content sites, API wrappers |
+| B | moderate | file processing, 3rd-party integrations, auth via library, single LLM call, HITL AI drafts |
+| C | expensive | realtime, payments from scratch, custom auth, autonomous agentic AI pipelines, heavy concurrency |
+
+**Grade is a COST estimate, not a permission.** The gate is fit(grades, budget), not "no C allowed."
+When a C feature is the real need, three honest paths:
+1. **The C feature IS the product** → invert the cut: C goes FIRST (riskiest assumption first),
+   everything else is minimized to serve it, and the budget is renegotiated against reality.
+   But: one C proves the value prop — its siblings are v2 cards, not v1 scope.
+2. **Re-architect C down to B** (highest-leverage move): multi-step agent → single LLM call;
+   auto-send → human-approves-draft; custom pipeline → managed service / library.
+   Same user value, one grade cheaper.
+3. **Irreducible C that doesn't fit the budget** → KILL or re-budget. Both are honest.
+
+## Gate — check ALL before `/flow next`
+- [ ] Every feature below has an IMPACT (H/M/L with the business reason) AND a grade (A/B/C)
+- [ ] No L-impact feature above grade A survives in v1
+- [ ] The suggested-features section was actually considered (each suggestion has an in/out decision)
+- [ ] fit(grades, budget) holds — every C in scope is justified as path 1, 2, or 3 above (written next to the feature)
+- [ ] If the product IS a C feature: it is FIRST in build order, and its sibling C features are on the cut list
+- [ ] The cut list is written (what I am NOT building in v1)
+- [ ] GO / KILL decision is written below
+- [ ] No FILL placeholders remain in this file
+
+## Time budget
+
+[FILL: e.g. "2 weekends" / "20 hours"]
+
+## Features in v1 (each with impact AND grade)
+
+- [FILL: feature — impact H/M/L (business reason: acquisition/revenue/retention/core job) — grade A/B/C — why]
+
+## Suggested features (impact-first — proposed, not decided)
+
+Up to 3 features NOT in the original idea, each chosen for business impact (how does this
+get users in / get money in / keep users?). Grounded in the stage-01 GTM findings — e.g.
+the first-10-users channel often implies a share/invite/referral surface; the pricing
+research often implies an upsell or a paid tier. Default is OUT; each needs an explicit
+decision.
+
+- [FILL: suggestion — impact + why (tie to GTM research) — grade — IN or OUT + reason]
+
+## Cut list (NOT in v1 — deferred, not deleted)
+
+- [FILL: feature — why deferred]
+
+## Decision
+
+[FILL: GO or KILL — one sentence why]

package/skills/flow/_templates/03-prd.md

@@ -0,0 +1,57 @@
+# Stage 03 — PRD
+
+1-2 pages max. Test: could a stranger build v1 from this without asking you anything?
+
+## Gate — check ALL before `/flow next`
+- [ ] Every section below is filled from MY scope decision (stage 02), not re-expanded
+- [ ] Success metric is a NUMBER, not vibes ("save time" fails; "first response < 2h" passes)
+- [ ] Each feature names the user action and the observable result, tagged with a stable `FRn:` id
+- [ ] Pain & gain is a MAPPING TABLE: every pain cites evidence (a stage-01 quote or a named observation), and names the v1 feature that kills it; every v1 feature kills at least one pain
+- [ ] A stranger could build v1 from this without asking me anything
+- [ ] No FILL placeholders remain in this file
+
+## Context
+
+[FILL: 3-5 sentences — the situation this product enters]
+
+## Target users
+
+[FILL: persona(s) — who, demographic, behavior. Reuse stage 00/01 evidence.]
+
+## Pain & gain (mapping table — the traceability spine of the PRD)
+
+Every row: a concrete pain, the evidence it's real, what people do about it today, the
+ONE v1 feature that kills it, and the observable gain. If a feature kills no pain, cut
+it; if a pain has no feature, it goes to the "not addressed" list — honestly.
+
+| # | Persona | Pain (concrete) | Evidence (stage-01 quote/source or named observation) | Today's workaround | V1 feature that kills it | Observable gain |
+|---|---|---|---|---|---|---|
+| P1 | [FILL] | [FILL] | [FILL] | [FILL] | [FILL] | [FILL] |
+
+### Pains NOT addressed in v1 (deliberate — tie to the scope cut list)
+
+- [FILL: pain → why deferred / which v2 item covers it]
+
+## Problem statement
+
+[FILL: 1-2 sentences]
+
+## Features (user-centric — action → observable result)
+
+Tag each v1 feature with a stable id `FRn:` (functional requirement) — the traceability
+anchor. Every `FRn` must later be claimed by a card (`implements: FRn`) and served by an
+interface in the contract (`FRn →`); `/flow consistency` checks this mechanically.
+
+- [FILL: "FR1: As a <user>, I <action>, and I see <result>" — one per v1 feature from stage 02]
+
+## Non-functional requirements
+
+[FILL: only the ones that matter for v1 — e.g. mobile-first, page load, no-login]
+
+## Tech stack
+
+[FILL: backend / db / frontend / deploy target — name specific choices]
+
+## Success metric (numbers only)
+
+[FILL: e.g. "10 tickets filed by real residents in week 1; median first-response < 2h"]

package/skills/flow/_templates/04-adr.md

@@ -0,0 +1,21 @@
+# Stage 04 — ADR (architecture decisions)
+
+Short. The most valuable section is what you are NOT doing and why.
+
+## Gate — check ALL before `/flow next`
+- [ ] Each decision has a one-line "why" and a one-line "what I rejected"
+- [ ] The NOT-doing list is written
+- [ ] Decisions cover: data storage, auth approach, deploy target
+- [ ] No FILL placeholders remain in this file
+
+## Decisions
+
+| # | Decision | Why | Rejected alternative |
+|---|---|---|---|
+| 1 | [FILL: e.g. Postgres single schema] | [FILL] | [FILL] |
+| 2 | [FILL: e.g. magic-link tokens, no accounts] | [FILL] | [FILL] |
+| 3 | [FILL: e.g. deploy on X] | [FILL] | [FILL] |
+
+## NOT doing in v1 (and why it's safe to skip)
+
+- [FILL]

package/skills/flow/_templates/05-contract.md

@@ -0,0 +1,59 @@
+# Stage 05 — Interface Contract (the seam)
+
+The contract is whatever sits between your core and its consumer. For a web app that's
+API endpoints (the table below). For a CLI it's commands + flags + output shapes; for a
+plugin it's hooks + filters; for a pipeline it's input/output file schemas. Keep the
+table's SPIRIT — every feature maps to an interface, every interface has its shapes
+written before code — and adapt the columns to your project's shape.
+
+Written BEFORE any code. Backend cards build TO this table; UI cards consume FROM it.
+The #1 AI-build failure is producer/consumer drift — backend ships one shape, UI assumes
+another, both look green. This file is the cheap fix.
+
+## Gate — check ALL before `/flow next`
+- [ ] Every PRD feature maps to at least one INTERFACE below (web: endpoint · cli: command · library: public function · skill: command/file)
+- [ ] Every interface has its INPUT and OUTPUT shapes written (web: request+response · cli: flags+output/exit code · library: args+return)
+- [ ] Access/effects column filled for every interface (web: public/token/admin · non-web: writes/side-effects, or "none")
+- [ ] No FILL placeholders remain in this file
+
+## OpenAPI / Swagger rule  (web only — N/A for cli/library/skill)
+
+For non-web types there is no served spec; the equivalent "no producer/consumer drift" check
+is the per-type done-evidence (the command runs / the API imports / the skill installs+runs).
+For `web`:
+
+This table is the PLANNING source of truth. If the framework serves a spec (FastAPI →
+`/openapi.json` + `/docs`), the served spec is the RUNTIME artifact of this same contract:
+- Path/method/shapes here and in the served spec must agree — the contract-test card
+  asserts every endpoint in this table exists in the live `/openapi.json` with matching
+  request/response shapes.
+- Change flows ONE way: amend this file first, then the code, then the spec follows.
+- **Docs land with the API, not after**: the served spec is live from the vertical-slice
+  card onward, and every backend card's verify checks its endpoints appear in the live
+  `/docs` with correct schemas. The contract-test card later asserts full agreement —
+  but by then the docs have been growing card by card, never a catch-up task.
+- Keep `/docs` enabled at least until v1 ships — it's the free human-readable contract.
+
+## Interfaces  (web: endpoints · cli: commands · library: functions · skill: commands)
+
+Adapt the columns to your project type. Web: Method/Path/Access(=auth: public/token/admin)/
+Request/Response. CLI: Command/Flags/Access(=side-effects)/Input/Output+exit. Library:
+Function/—/Access(=none)/Args/Return. The shared column below is "Access/Effects".
+
+| Method/Interface | Path/Name | Access/Effects | Input shape | Output shape |
+|---|---|---|---|---|
+| [FILL] | [FILL] | [FILL] | [FILL] | [FILL] |
+
+## Shared shapes (objects used by multiple interfaces)
+
+```
+[FILL: e.g. (web)  Ticket { id, category, status: open|in_progress|resolved, created_at, ... }
+       e.g. (cli)  --output json|table ; exit 0=ok 1=usage 2=error ]
+```
+
+## Feature → interface map
+
+Reference each PRD feature by its `FRn` id so the mapping is machine-checkable
+(`/flow consistency` flags any `FRn` with no interface here).
+
+- [FILL: FR1 → interface(s) that serve it]

package/skills/flow/_templates/card.md

@@ -0,0 +1,26 @@
+# C-NNN — [FILL: one-line scope, ONE thing]
+
+status: todo
+deps: [FILL: card ids this depends on, e.g. "C-001, C-002" — or "none"]
+implements: [FILL: PRD feature ids this card delivers, e.g. "FR1, FR2" — or "infra"/"none" for non-feature cards]
+
+## Scope
+
+[FILL: exactly what this card builds. If it's two things, split it.]
+
+## Allowed files
+
+[FILL: which files/dirs this card may touch — keeps the diff reviewable]
+
+## Verify (run these before calling the card done)
+
+- [ ] [FILL: a concrete check — a curl, a click, a command + expected output]
+
+## Done-evidence (world-state proof, named BEFORE building)
+
+[FILL: what will be observable in the world when this is done — a URL you can click,
+a curl output, a deployed page. "Tests pass" / "code merged" are NOT done-evidence.]
+
+## Evidence (paste the actual proof here when done)
+
+(empty until done)

package/skills/flow/_templates/constitution.md

@@ -0,0 +1,22 @@
+# Project Constitution — operator-authored invariants
+
+Non-negotiable rules for THIS project, enforced as a **two-layer advisory gate**:
+- **mechanical** — `flow.sh constitution` checks structure (no leftover placeholder, every
+  invariant has a stable ID) and advisory-scans any declared grep-marker under `src/`.
+- **semantic** — at the scope / PRD / contract gates, Claude challenges each artifact against
+  these invariants (see `references/gate-rules.md` → "Constitution challenge").
+
+This is **advisory and per-project**. It does NOT replace the security-class Tier-C halt. It is
+intentionally **NOT wired into `/flow next`** — run it yourself at the scope/PRD/contract seam.
+
+## Invariants
+
+Each row: a stable **ID**, the **rule**, the **stages** it applies at, an OPTIONAL **grep-marker**
+(a regex that should appear in code when the invariant holds — put `-` for semantic-only rules; if
+the regex needs a literal `|` alternation, escape it as `\|` so it survives the table cell),
+and the **rationale**.
+
+| ID | Invariant | Applies-at | grep-marker (optional) | Rationale |
+|----|-----------|-----------|------------------------|-----------|
+| INV-1 | [FILL: e.g. all PII access is facility-scoped] | scope,prd,contract | [FILL: e.g. facility_id  — or  -] | [FILL: why this must always hold] |
+| INV-2 | [FILL: e.g. no API surface ships without an entry in flow/05-contract.md] | contract,cards | - | [FILL] |

package/skills/flow/eval/fixtures/f01a/flow/01-research.md

@@ -0,0 +1,77 @@
+# Stage 01 — Research (inspect first)
+
+Rule: INSPECT what already exists. Evidence required — links, quotes, screenshots.
+"I think there's nothing like this" without searching = gate fail.
+
+## Gate — check ALL before `/flow next`
+- [x] I actually OPENED 3 existing tools/competitors (links below, with one honest note each)
+- [x] I found 3 REAL user complaints online, quoted, with source links
+- [x] I wrote what competitors CHARGE (real prices) and who pays
+- [x] I named the ONE channel my first 10 users come from (a place, not "social media")
+- [x] I wrote why those users would pick this over the status quo (one honest paragraph)
+- [x] I wrote what is technically free vs hard for this idea
+- [x] No FILL placeholders remain in this file
+
+## What exists already (3 — open them, don't guess)
+
+1. Splitwise (splitwise.com) — handles group expense splitting well, but its recurring-bill
+   view buries anything not tagged "rent"; three of our pilot households gave up trying to
+   track a shared internet bill inside it and moved back to a spreadsheet.
+2. Tricount (tricount.com) — clean mobile UI, free tier caps a group at 1 currency and no
+   CSV export unless you pay; the export paywall is the exact friction our target users hit
+   when they try to reconcile at month-end.
+3. A shared Google Sheet template (the informal incumbent most of our interviewees actually
+   use today) — zero cost, but no reminders, no per-person balance view, and it silently
+   breaks when two people edit the same cell at once (three separate households reported
+   losing an entry this way in the last three months).
+
+## What users say (3 real complaints quoted+linked)
+
+1. > "Splitwise is great until someone doesn't open the app for two weeks and the balance
+   >  just sits there. I want a nudge, not a number."
+   — u/frugal_flatmate, r/personalfinance thread "How do you actually get roommates to pay
+   you back?" (reddit.com/r/personalfinance/comments/17k2xq1)
+2. > "We tried three apps and gave up and went back to a spreadsheet because none of them
+   >  let us split a bill three unequal ways without doing the math ourselves first."
+   — comment on Tricount's App Store listing (apps.apple.com/us/app/tricount/id594204643,
+   review dated within the last 6 months)
+3. > "Every month it's the same fight about who forgot to pay for internet. I don't need
+   >  another budgeting app, I need someone to just tell me the number."
+   — reply on r/Roommates, thread "what bill split apps have worked for you long term"
+   (reddit.com/r/Roommates/comments/1a8j9k2m/what_bill_split_apps_have_worked_for_you/), posted
+   by u/threeway_hcol_split within the last 4 months
+
+## GTM & business reality
+
+Building is the cheap part now. Distribution and willingness-to-pay are where ideas die —
+research them BEFORE planning, not after shipping.
+
+### Who pays today, and how much (pricing reference points)
+
+- Splitwise Pro — $3/month or $30/year, paid by the household member who "owns" the group.
+- Tricount CSV export — one-time IAP of $2.99, paid by whoever needs the bank reconciliation.
+- Manual spreadsheet — $0 cash cost, but our pilot households estimate ~25 minutes/month of
+  someone's unpaid time reconciling it, which is the real cost we are competing against.
+
+### The first-10-users channel
+
+The Facebook group "Da Nang Expat Roommates & Housing" (11k members, admin-approved posts
+only on Mondays) — two of the founders already have posting rights there from a prior
+apartment-hunting post that got 40 comments; that thread is where 6 of our 8 pilot
+households were originally recruited from.
+
+### Why switch (vs the status quo)
+
+The named households in that Facebook group are currently using a shared Google Sheet that
+breaks under concurrent edits and has no reminder mechanism; they already told us (during
+the pilot interviews) that they'd pay a small one-time fee to stop the monthly "who forgot"
+argument, provided the switch takes under 5 minutes and doesn't require the whole household
+to create new accounts.
+
+## Technically free vs hard
+
+- Free (solved by libraries/platforms): auth via a magic-link email provider, expense CRUD,
+  push notifications via a managed service (OneSignal free tier covers our pilot scale).
+- Hard (custom work, real risk): the "who forgot" nudge logic needs a debt-simplification
+  algorithm (minimize the number of repayment transactions across an N-person group) — this
+  is a small graph problem, not off-the-shelf, and the first version will hand-roll it.

package/skills/flow/eval/fixtures/f01b/flow/01-research.md

@@ -0,0 +1,75 @@
+# Stage 01 — Research (inspect first)
+
+Rule: INSPECT what already exists. Evidence required — links, quotes, screenshots.
+"I think there's nothing like this" without searching = gate fail.
+
+## Gate — check ALL before `/flow next`
+- [x] I actually OPENED 3 existing tools/competitors (links below, with one honest note each)
+- [x] I found 3 REAL user complaints online, quoted, with source links
+- [x] I wrote what competitors CHARGE (real prices) and who pays
+- [x] I named the ONE channel my first 10 users come from (a place, not "social media")
+- [x] I wrote why those users would pick this over the status quo (one honest paragraph)
+- [x] I wrote what is technically free vs hard for this idea
+- [x] No FILL placeholders remain in this file
+
+## What exists already (3 — open them, don't guess)
+
+1. Splitwise — a well known bill-splitting app used by a lot of people, and honestly one of
+   the first names that comes up whenever this category is discussed. It covers the basics
+   of group expense tracking reasonably well, and most people who have shared a household
+   or gone on a group trip have probably at least heard of it, even if they haven't used
+   every feature it offers.
+2. Tricount — another popular option in this space, generally well reviewed by the people
+   who use it, with a clean enough interface that most users seem to figure it out without
+   much trouble. It's often mentioned alongside Splitwise as one of the go-to choices when
+   this kind of problem comes up in conversation.
+3. Various spreadsheet templates people use informally, which is honestly still the default
+   fallback for a lot of households — there are plenty of templates floating around online,
+   and they get the job done for people who don't want to bother installing another app for
+   something they might only need occasionally.
+
+## What users say (3 real complaints quoted+linked)
+
+1. > "This kind of app never really works for my group."
+   — users online, in a discussion I came across while looking into this space generally
+2. > "I wish there was something better for splitting bills with roommates."
+   — a comment I saw somewhere while browsing around for feedback on existing tools
+3. > "Everyone I know complains about this problem."
+   — general sentiment from users, based on conversations and things people have mentioned
+   in passing when this topic comes up among people I know
+
+## GTM & business reality
+
+Building is the cheap part now. Distribution and willingness-to-pay are where ideas die —
+research them BEFORE planning, not after shipping.
+
+### Who pays today, and how much (pricing reference points)
+
+- Splitwise has a paid tier, roughly a few dollars a month, paid by people who use it a lot
+  and want the extra features that come with the paid version, though most casual users
+  probably just stick with the free tier and never bother upgrading.
+- Tricount also has some kind of paid option for extra features, similar in spirit to how
+  Splitwise structures things, aimed at people who need more than the basic functionality.
+- Spreadsheets are free but take time, which has some cost to people even if it's not a
+  direct cash expense — the time adds up, especially for groups that update it often.
+
+### The first-10-users channel
+
+Social media — we'll post about it and see who's interested, probably starting with some
+online groups and general word of mouth once we launch, since that tends to be how a lot
+of similar apps have found their early users historically, from what I understand.
+
+### Why switch (vs the status quo)
+
+Users would switch because our app is simpler and better designed than what's currently
+out there, and people generally prefer a nicer experience once they try it, especially
+once they see how much smoother the whole process feels compared to what they're used to.
+
+## Technically free vs hard
+
+- Free (solved by libraries/platforms): most of the basic app functionality, using standard
+  tools and frameworks that are widely available and well documented, so there shouldn't be
+  much reinventing of the wheel needed for the core plumbing.
+- Hard (custom work, real risk): making the whole thing feel polished and handling all the
+  edge cases that come up once real users start using it in ways we didn't originally plan
+  for, which tends to be where a lot of the actual effort ends up going in practice.

package/skills/flow/eval/fixtures/f02a/flow/02-scope.md

@@ -0,0 +1,56 @@
+# Stage 02 — Scope (go/no-go)
+
+Scope = features chosen by IMPACT × COST, inside your time budget.
+KILL here is cheap and smart. Killing a weak idea at this gate is a SUCCESS outcome.
+
+## Gate — check ALL before `/flow next`
+- [x] Every feature below has an IMPACT (H/M/L with the business reason) AND a grade (A/B/C)
+- [x] No L-impact feature above grade A survives in v1
+- [x] The suggested-features section was actually considered (each suggestion has an in/out decision)
+- [x] fit(grades, budget) holds — every C in scope is justified as path 1, 2, or 3 above (written next to the feature)
+- [x] If the product IS a C feature: it is FIRST in build order, and its sibling C features are on the cut list
+- [x] The cut list is written (what I am NOT building in v1)
+- [x] GO / KILL decision is written below
+- [x] No FILL placeholders remain in this file
+
+## Time budget
+
+3 weekends (roughly 24 hours of build time)
+
+## Features in v1 (each with impact AND grade)
+
+- Expense entry + equal/unequal split — impact H (core job: this is the one thing users
+  came for) — grade A (CRUD form over a shared-group data model)
+- Magic-link email auth — impact H (acquisition: no password friction for the first-10
+  household to onboard) — grade B (third-party auth library, not custom) — path 2:
+  re-architected from a custom session system to a managed magic-link provider
+- Debt-simplification nudge (who-owes-whom, minimized transaction count) — impact H (this
+  is the actual differentiator named in stage-01 research: "I want a nudge, not a number")
+  — grade C (a real graph-minimization algorithm, not off-the-shelf) — path 1: this C IS
+  the product's differentiator, so it goes FIRST in build order (before auth polish or
+  CSV export), and no sibling C features are scoped alongside it in v1
+- Push reminder when a balance sits unpaid for 7+ days — impact M (retention: keeps the
+  household using it instead of drifting back to the spreadsheet) — grade A (managed push
+  notification service, OneSignal free tier)
+
+## Suggested features (impact-first — proposed, not decided)
+
+- CSV export for bank reconciliation — impact M (retention/trust: matches the exact
+  friction named in stage-01, "we gave up because we couldn't reconcile at month-end") —
+  grade A (structured data → CSV is a solved problem) — IN: cheap and directly answers a
+  named pain, added to v1 cut list re-evaluation next cycle, deferred to v1.1 because the
+  3-weekend budget is already fully allocated to the four features above
+- Multi-currency support — impact L (nobody in the named first-10 household group travels
+  or splits in a second currency) — grade B (real but not trivial: exchange-rate handling)
+  — OUT: L-impact above grade A is cut per the gate rule
+
+## Cut list (NOT in v1 — deferred, not deleted)
+
+- CSV export — deferred to v1.1, see suggested-features reasoning above
+- Multi-currency support — deferred indefinitely unless a pilot household actually needs it
+- In-app chat between household members — nice-to-have, no named user asked for it
+
+## Decision
+
+GO — the core differentiator (debt-simplification nudge) is a real but bounded C feature,
+sequenced first per path 1, and the rest of v1 stays at grade A/B within the 24-hour budget.