vinta-ai-workflows 0.1.7

package/skills/vinta-derive-skills/resources/foundation-skills/create-qa-use-cases/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: create-qa-use-cases
+description: Bootstrap a project's `QA_USE_CASES.md` from scratch using the canonical pattern (immutable PA###/PR### ids, role table, per-app numbered sections with role-tagged checklists). Invoked from inside [plan-feature](../plan-feature/SKILL.md) when the project has no `QA_USE_CASES.md` yet — the active feature's spec + plan are already in hand. Seeds the file with use cases from those two documents only; does not sweep prior plans. Asks the user for the few gaps spec/plan don't answer (app boundaries, role list, prefix conventions). Project-agnostic — works in any repo that adopts this skill set.
+---
+
+# Bootstrap `QA_USE_CASES.md`
+
+The doc maps 1:1 to e2e test specs by an immutable id. It's the QA team's manual-test checklist and the spec filename source of truth. [add-e2e-test](../add-e2e-test/SKILL.md) appends entries; this skill creates the file the first time, **seeded from the active feature** that triggered the bootstrap.
+
+## When to use
+
+- Project has no `QA_USE_CASES.md` at the repo root.
+- [plan-feature](../plan-feature/SKILL.md) is in flight for a specific feature — its spec + plan are the seed material.
+- A UI-flow phase in that plan needs an e2e id but the file doesn't exist yet.
+
+If `QA_USE_CASES.md` already exists, **do not overwrite**. Stop and route the user to [add-e2e-test](../add-e2e-test/SKILL.md) for appending entries. Bootstrap is one-shot.
+
+## Source: the active feature only
+
+This skill runs **inside** the plan-feature flow, so the active spec + plan are already loaded into the conversation. Seed the file from those two documents — **do not** sweep `ai-plans/` for prior specs. Older features that pre-date this doc will be added later via [add-e2e-test](../add-e2e-test/SKILL.md) as they need test coverage; bootstrapping with the entire history is noise.
+
+Extract from the active feature's docs:
+
+1. **Use cases** from the spec's **Decisions → Use-cases** section (one PA/PR entry per user-facing flow). UI-affecting phases from the plan's **Phased Rollout** that aren't already in the spec's **Use-cases** get an entry too.
+2. **Role list** from the spec's **Business Context** / **Decisions → Use-cases** actors + the plan's **Guiding Decisions**.
+3. **App boundaries** if the spec/plan name them; otherwise ask.
+
+If invoked standalone (not from plan-feature), ask the user *"Which spec + plan should I seed from?"* via `AskUserQuestion` and load only those two files. Don't go fishing.
+
+## Decision questions
+
+For everything **not** answered by the active spec/plan, ask via `AskUserQuestion`. Closed-form questions go through the tool; open narrative questions iterate one at a time. Same convention as [plan-feature](../plan-feature/SKILL.md) and [create-spec](../create-spec/SKILL.md).
+
+### Questions to ask (skip when source docs answer)
+
+**A. App boundaries**
+1. How many apps does this project have, and what are their names? (e.g. `Patient App`, `Provider App`, `Admin Console`, single SaaS app named `<Product>`.)
+2. ID prefix per app — typically a 2-letter abbreviation. Defaults: `PA` for "patient/public app", `PR` for "provider/admin app". Confirm or override.
+3. Does any app have unauthenticated routes that need use-case entries (registration, public referral, marketing landing)? Those entries note `(unauthenticated)` in the role.
+
+**B. Roles**
+1. List of roles that perform actions in any app. Each role: name + which app(s) it logs into + one-sentence description.
+2. Is there an "Admin" or "Super-Admin" role distinct from regular users? Many projects' permission docs distinguish project-admin (`ProjectMembership.admin === true`) from role-coded admins — both belong in the table if both exist.
+3. Are external actors (referring providers, integration partners) ever actors in a use case? Note as `(unauthenticated)` or `(external — no login)`.
+
+**C. Active-feature coverage**
+1. From the active spec + plan, here's the use-case list I extracted: `<list>`. Anything missing or mis-scoped? (`AskUserQuestion` with `Looks good` / `Some corrections (I'll list)` / `More to add` / `Stop, rethink`.)
+2. For each use case, who's the role? If the source says "Care Coordinator, Physician" pick one default and note the others. Multi-role use cases are normal — comma-separate them in the entry.
+
+**D. ID assignment**
+1. Order: append in the order use cases appear in the active spec (**Decisions → Use-cases** first, then any plan-only phases). Don't reshuffle.
+2. Default starting numbers `PA001` / `PR001`. Confirm or override.
+
+### Clarity loop
+
+Same as the other interview skills. After each `AskUserQuestion` round, re-scan: did the answer reveal a new role? A use case that needs splitting? An app boundary I missed? Open another batch. Exit conditions:
+
+- Every app named + prefix assigned.
+- Every role listed with app + description.
+- Every spec use case mapped to one or more roles + assigned an id.
+- No "we'll figure that out later" in the role table — that's a live ambiguity, ask now.
+
+Final read-back via `AskUserQuestion`: *"Anything I got wrong before I write the file?"* with `Looks good` / `Some corrections (I'll list)` / `More to clarify` / `Stop, rethink`. Only write on `Looks good`.
+
+## File structure (canonical)
+
+```markdown
+# {Project Name} Use Cases
+
+IDs (`PA###` for {patient app name}, `PR###` for {provider app name}) are immutable. When
+adding a new use case, pick the next unused number — never reshuffle, renumber,
+or reuse a retired ID. The e2e spec filenames mirror these IDs one-to-one.
+
+## Roles
+
+| Role | App | Description |
+|------|-----|-------------|
+| **{Role 1}** | {App} | {One-sentence description} |
+| **{Role 2}** | {App} | {…} |
+| …
+
+---
+
+## {Patient / First App}
+
+### PA001. {Use Case Title}
+
+**Role:** {Role(s) — comma-separated if multi-role; add `(unauthenticated)` for public flows}
+
+- [ ] {First step the user takes}
+- [ ] {Next step}
+- [ ] {Verify {observable outcome}}
+  - {Sub-bullet for branched outcomes — e.g. eligible vs ineligible paths}
+
+### PA002. {…}
+
+…
+
+---
+
+## {Provider / Second App}
+
+### PR001. …
+
+…
+```
+
+### Step-list rules per entry
+
+- **Verb-led, present tense.** "Navigate to /settings", "Click Save", "Verify the success toast appears". Not "User navigates", not "Should click".
+- **Checkboxes (`- [ ]`)** because the doc doubles as a manual-test checklist. QA ticks them off in PRs.
+- **One observable assertion per branch.** "Verify eligibility result: If eligible → redirected to /onboarding. If ineligible → error message shown." Mirrors how the e2e spec is structured.
+- **Reference URL paths exactly** as the app routes them (`/settings`, `/onboarding/{uniqueId}`). Reviewer can follow without context.
+- **Never include implementation details.** No domain model names, API endpoints, table names, or library specifics. Doc is read by QA, product, support — keep it user-language.
+
+### Multi-app projects
+
+- One `## ` section per app, separated by `---`.
+- Section heading = exact app name as it appears in the role table.
+- Prefix per app is consistent within the section: PA-section uses `PA001…`, PR-section uses `PR001…`.
+- Don't interleave apps under one section.
+
+### Single-app projects
+
+Skip the `---`-separated sections. Single `## Use Cases` heading, one prefix (e.g. `UC001`).
+
+## Checklist
+
+### 1. Confirm no existing file
+
+If `QA_USE_CASES.md` exists at repo root, **stop**. Tell the user the file already exists and route them to [add-e2e-test](../add-e2e-test/SKILL.md) for appending. Bootstrap doesn't merge or migrate — that's manual work, not a skill output.
+
+### 2. Pull from the active spec + plan only
+
+The active feature's spec + plan are already in the conversation (handed in by [plan-feature](../plan-feature/SKILL.md), or pointed to by the user when invoked standalone). Extract:
+- Use cases from the active spec's **Decisions → Use-cases**.
+- UI-facing phases from the active plan's **Phased Rollout** that aren't already in the spec's **Use-cases**.
+- Roles from the active spec's **Business Context** / **Decisions → Use-cases** actors.
+
+**Do not** sweep `ai-plans/` for older specs. Pre-existing features that pre-date the doc get added later via [add-e2e-test](../add-e2e-test/SKILL.md) when they need test coverage.
+
+### 3. Run the interview
+
+Ask only for what the source docs don't already answer. Closed-form via `AskUserQuestion` (batched per group). Open-ended (extra context, narrative) iterate one at a time. Read back, confirm, loop until stable.
+
+### 4. Write the file
+
+Output to repo root: `QA_USE_CASES.md`. Use the canonical structure above. Plug in:
+- Project name in the title.
+- App names in the section headings + the immutable-ids note.
+- Role table with every role from the interview.
+- Numbered entries, ids in source-doc order, role line, step checklist.
+
+### 5. Tell the user what's next
+
+After writing:
+- Point to [add-e2e-test](../add-e2e-test/SKILL.md) for adding e2e specs that mirror these ids.
+- If [plan-feature](../plan-feature/SKILL.md) is in flight, remind the user that each UI-flow phase needs an entry here matched 1:1 to the spec it ships.
+- If new use cases come up later, append — never insert in the middle, never renumber.
+
+## Worked example (for shape only — not actual content)
+
+```markdown
+# Acme Sleep Use Cases
+
+IDs (`PA###` for Patient App, `PR###` for Provider App) are immutable. When
+adding a new use case, pick the next unused number — never reshuffle, renumber,
+or reuse a retired ID. The e2e spec filenames mirror these IDs one-to-one.
+
+## Roles
+
+| Role | App | Description |
+|------|-----|-------------|
+| **Patient** | Patient App | End-user receiving sleep care services |
+| **Provider: Care Coordinator (RN)** | Provider App | Coordination + admin |
+| **Provider: Physician (MD)** | Provider App | Clinical authority |
+| **Provider: Clinical Ops (Admin)** | Provider App | System administrator |
+
+---
+
+## Patient App
+
+### PA001. Self-Referral Registration
+
+**Role:** Patient (unauthenticated)
+
+- [ ] Navigate to the landing page
+- [ ] Click "Register"
+- [ ] Fill out the self-referral intake form
+- [ ] Submit
+- [ ] Verify eligibility:
+  - If eligible: redirected to `/onboarding/{uniqueId}`
+  - If ineligible: error message shown with "Go Back" option
+
+### PA002. …
+
+---
+
+## Provider App
+
+### PR001. Provider Sign In
+
+**Role:** All Providers
+
+- [ ] Navigate to the provider app landing page
+- [ ] Click "Sign In"
+- [ ] Enter credentials
+- [ ] Verify redirect to the patient list
+```
+
+## Pitfalls
+
+- **Overwriting an existing file.** Bootstrap is one-shot. If the file exists, append via add-e2e-test, don't regenerate — existing ids are referenced by spec filenames + bug tickets and can't move.
+- **Inventing use cases from project name alone.** If the spec/plan doesn't describe a flow, don't add a stub. Empty checklist + no real flow = noise. Ask the user; if they don't have one, leave it out.
+- **Mixing role-coded admin with project-admin.** Many systems have both (a "Clinical Ops" role + a flag like `ProjectMembership.admin === true`). List both rows in the role table if both apply — they map to different storage states / permission paths in tests.
+- **Putting implementation details in steps.** "Create QuestionnaireResponse with linkId=first-name" reads to QA as gibberish. "Fill out the intake form" is the right level. Implementation details belong in the e2e spec or seed helper, not here.
+- **Numbering by importance.** Numbers reflect order of arrival, not priority. PA047 isn't more important than PA003 — it just came later. Don't try to keep "core" use cases at low numbers; that path leads to renumbering.
+- **Skipping the `(unauthenticated)` annotation.** Public flows (registration, password reset, public referral) need it explicitly so reviewers know which storage state the e2e spec uses.
+- **Sweeping `ai-plans/` for older specs.** This skill seeds from the **active feature only**. Backfilling the doc with every historical feature creates phantom test obligations. Pre-existing features get added later via [add-e2e-test](../add-e2e-test/SKILL.md) when they actually need coverage.
+- **Generating without reading the active spec/plan.** The whole point is to inherit decisions, not re-derive them. If the active spec/plan are visible, read them. If they aren't, ask the user to point at them — don't guess.
+
+## Verification
+
+After writing the file:
+
+1. Open it. Render in a markdown previewer — table renders, sections appear in order, no broken markdown.
+2. Cross-check: every use case from every spec's **Decisions → Use-cases** appears as a numbered entry. None missing.
+3. Cross-check: every role mentioned anywhere in the entries appears in the role table.
+4. Cross-check: ids start at `001` per app prefix, ascend with no gaps.
+5. Run `grep -c '^### P[AR][0-9]' QA_USE_CASES.md` — count matches your interview tally.
+
+If [plan-feature](../plan-feature/SKILL.md) is in flight, the next step is creating one e2e spec per UI-flow phase — see [add-e2e-test](../add-e2e-test/SKILL.md). Each spec filename mirrors the id you just assigned.

package/skills/vinta-derive-skills/resources/foundation-skills/create-spec/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: create-spec
+description: Turn raw feature prompt into structured spec doc at `ai-plans/YYYY-MM-DD-FEATURE_NAME_SPEC.md`. Sections fixed — Business Context, Hypothesis, Objectives, Decisions (Use-cases / State transitions & edge cases / Acceptance scenarios / Negative scope), Alternatives considered (optional), Open questions, Risks assumed. Use when user asks "write a spec", "draft a spec doc", "turn this idea into a spec", or hands one-line / paragraph feature description needing structure before plan. Skill ALWAYS interviews requester before drafting — never turn vague prompt into plausible-sounding spec by guessing.
+---
+
+# Spec Document
+
+Spec **frame problem + solution boundaries** before plan. Precedes [plan-feature](../plan-feature/SKILL.md): spec answer *"what + why?"*; plan answer *"how, in what order, with what tests"*. Different artefact, different audience (spec → product + eng leadership; plan → implementer).
+
+Output: `ai-plans/YYYY-MM-DD-FEATURE_NAME_SPEC.md` (uppercase + underscores, today date prefix). Structure fixed; content from interview, not inference.
+
+## Step 0 — Interrogate before drafting (NON-NEGOTIABLE)
+
+Biggest failure: AI take one-liner ("add tags to orders") + confidently produce three pages of plausible-sounding context, hypothesis, acceptance criteria requester didn't say. **Don't.** Even when prompt look self-explanatory, ask. Even when answer feel obvious — your "obvious" is training-data average; theirs is *their* business.
+
+Ask below in batched, numbered chunks. Skip group only when prompt **explicitly** answers it; never because you can plausibly fill in.
+
+For finite-set answers, **list options**. Provide one-sentence **why** so they understand implications.
+
+### Use `AskUserQuestion` for finite-choice questions
+
+Every interview question with discrete answer set — yes/no, named option, finite enum, hypothesis-vs-known-requirement, idempotency mode, concurrency rule — **must** issue via `AskUserQuestion` tool. Use plain prose only when answer genuinely open-ended (problem narrative, walking through journey, free-form motivation, hard deadline date).
+
+Pattern per group:
+
+- One `AskUserQuestion` call per group, batch multiple questions into same call when tool supports (each question carry own option set).
+- Short label per option; rationale ("default: per-user — confirm or override") goes in question header, not option label.
+- Open-ended sub-questions in same group → fall back to plain prose for those, send closed-form ones via `AskUserQuestion`. Don't force finite list when genuinely free text.
+
+If `AskUserQuestion` in deferred-tool list + not yet schema-loaded, call anyway — tool name fixed + harness surfaces it. **Never** flatten ten questions into one prose paragraph because tool not pre-loaded; that failure mode this skill exists to prevent.
+
+### Clarity loop — keep asking until done
+
+Step 0 isn't one-pass. After each round of answers, **scan for new gaps**: contradictions between answers, follow-ups one answer surfaces, decisions left vague another decision depends on. Open another batch for those. Repeat.
+
+Loop exit conditions (all required):
+- Every group A–I either fully answered or explicitly waived.
+- Every answer's downstream questions also asked + answered.
+- No "we'll figure that out later" — that's **Open questions** material; either has recommended default + owner + unblock condition, or resolved now.
+- Can write each **Decisions → Use-cases** entry (actor + trigger + flow + outcome) without inventing.
+- Can write **Decisions → Acceptance scenarios** without making up Given/When/Then.
+
+Any condition fails → another `AskUserQuestion` round. Don't shortcut to drafting just because you've done one batch.
+
+After answers stabilize: **read back one-paragraph summary** of every load-bearing decision. Then issue one final `AskUserQuestion` — single question *"Anything I got wrong before I draft?"* with options `Looks good`, `Some corrections (I'll list)`, `More to clarify`, `Stop, rethink`. `More to clarify` → another loop iteration. Only draft when user picks `Looks good`.
+
+User say *"just write the spec, I'll fix it"*: comply but mark every unverified inference under **Open questions** (preferred) or **Risks assumed** (when guess about how world is). Don't let assumptions hide inside Business Context or Decisions.
+
+### A — Problem & customer
+
+1. **Problem we solving — for whom?** Specific actor: tenant admins editing orders, ops staff fixing data, end users in dashboard, external integration partners, internal team.
+   *Why: "the customer" rarely single bucket; mixing them = optimize wrong workflow.*
+2. **What customer do today?** Manual workaround, support ticket, doesn't bother, leaves platform — name path + pain.
+   *Why: no current pain → no demand to validate. "Leaves platform" different objective than "saves 10 minutes/week".*
+3. **Cost today?** Lost revenue, support volume, churn risk, manual hours, compliance risk, integration breakage. Rough estimate fine.
+   *Why: becomes success metric in **Objectives**. Without it, "did this work?" has no answer.*
+4. **Who else care about this landing?** Other teams, integration partners, support, sales engineering, named stakeholder. Anyone who block rollout if not looped in.
+   *Why: surface hidden veto points before plan written.*
+
+### B — Hypothesis (falsifiable)
+
+1. **Change in behavior or metric expected?** State as `if we do X, then Y will improve by Z (within timeframe)`. Metric doesn't move → what tells us we wrong?
+   *Why: spec without falsifiable hypothesis = wish list. plan-feature requires this for rollout/soak window.*
+2. **Hypothesis or known requirement?**
+   - **Hypothesis** — "we think this improves X, but unsure". Validation matter; may roll back.
+   - **Known requirement** — "must do for compliance / customer / deadline". Correctness + timing matter, not validation.
+   - **Mixed** — both gates apply.
+   *Why: hypothesis-driven features need smaller gated rollouts + explicit kill criteria; known requirements need scope discipline + deadline awareness instead.*
+3. **What "validated" look like — concrete signal, source, threshold?** *(Hypothesis only.)* E.g. "support ticket volume drops 50% in 60 days, measured in Zendesk tag X".
+   *Why: vague "we'll see" doesn't survive contact with reality. Naming source up front prevent post-hoc cherry-picking.*
+4. **Failed validation — what then?** Roll back, iterate, accept + move on, deprecate?
+   *Why: force commitment to kill criterion before sunk-cost kicks in.*
+
+### C — Use cases
+
+1. **Walk through 1–3 concrete user journeys** end-to-end. Concrete: who initiate, what they click/send, what they see back, what side-effects fire.
+   *Why: abstract descriptions miss conditions making features hard. Concrete journeys force decisions about ordering, defaults, error states.*
+2. **Integration-driven (no human) flows hitting same path?** Webhook from upstream SaaS, scheduled function, batch import.
+   *Why: flows working for humans often break for integrations (omit-vs-empty, retry semantics, idempotency).*
+3. **Alternative entry points?** UI button + API + admin + Slack — anywhere same feature reachable.
+   *Why: each entry point may need own permissions, validation, audit log.*
+
+### D — State, edges, idempotency
+
+1. **States / lifecycle?** Name them + allowed transitions. Sketch as `Draft → Active → Archived` if unsure.
+   *Why: most "small" features turn out to have state machine. Drawing it out reveal forbidden transitions needing explicit handling.*
+2. **Edge cases, even half-formed?** Empty inputs, deleted parents, concurrent edits, partial failures, stale data, duplicates, oversized payloads, very-many-of-X.
+   *Why: requester know their business; their "weird thing once a month" exactly where bug live.*
+3. **Idempotency**: same request twice (retry, double-click, replay)?
+   - **Idempotent** — second is no-op, final state matches.
+   - **Append/duplicate** — only OK when duplicates are desired semantic (logging clicks).
+   - **Reject** — second errors with "already done".
+   *Why: most APIs here idempotent by default (bulk-upsert with last_updated_at guard). Drift cause data corruption expensive to recover.*
+4. **Concurrency**: two actors hit simultaneously on same entity? Resolution: last-write-wins, first-write-wins, optimistic lock with conflict surfaced?
+   *Why: silent last-write-wins eat user work; surface explicitly.*
+5. **Time-bounded behavior**: TTL, expiry, soak window, scheduled re-evaluation, "if user doesn't act within X, do Y"?
+   *Why: time-based rules need explicit specs or become invisible bugs.*
+
+### E — Acceptance scenarios
+
+1. **3–7 scenarios proving works**, in Given/When/Then form (or close — "if X, then Y"). At minimum:
+   - One happy path.
+   - One error / negative path (invalid input rejected with useful message).
+   - One edge case from D.
+   - One integration-driven flow if there is one.
+   *Why: become acceptance lines on plan phases + test matrix downstream.*
+
+### F — Negative scope
+
+1. **What might reasonable person assume in scope but you want excluded?** Be petty.
+   *Why: non-goals save most time. Without them, scope creep invisible until Phase 6.*
+2. **Deferred to v2 / v1.x?** Name each + reason (cost, complexity, no signal, blocked by something else).
+   *Why: deferred-with-reason only honest deferral. "Maybe later" usually mean "never, but I don't want to argue".*
+3. **What other systems / workflows should NOT change?** Existing endpoints whose contract must hold byte-for-byte, dashboards whose query shapes can't shift, integration payloads locked.
+   *Why: changes that look additive often touch shared infra. Calling out hands-off zones set rollback contract.*
+
+### G — Alternatives considered (optional)
+
+1. **What other approaches considered — why rejected?** Cost, risk, scope creep, doesn't solve real problem, regulatory blocker, unproven, vendor change. One sentence each.
+   *Why: make spec defensible six months later. No alternatives? Say so: "alternatives considered: none" valid signal.*
+
+### H — Constraints, deadlines, dependencies
+
+1. **Hard deadlines?** Compliance, customer commitments, partner integrations cutting over, regulatory window.
+   *Why: change urgency math; may force phases to overlap risk normally sequential.*
+2. **Existing systems / data we can't touch?** Frozen table, deprecated endpoint kept alive for one customer, contract under review.
+   *Why: usually appear as Phase-3 surprises.*
+3. **External dependencies** — integration partners (third-party SaaS APIs), other internal services / repos, other teams' deliverables. Who has to do what before this lands?
+   *Why: define deploy ordering. Spec ignoring slowest-moving dep ship late.*
+
+### I — Risks & assumptions
+
+1. **What could go wrong, how bad?** Migration data loss, user confusion, integration regression, perf regression on hot path, breakage of unrelated feature.
+   *Why: every spec has risks; question is which team willing to live with.*
+2. **What you assuming that might not hold?** "no tenant has more than 200 of these"; "integrations send X within 24h"; "schema can change without multi-step migration".
+   *Why: landmines if not surfaced. Once written, team can validate, design around, or accept.*
+3. **Reversibility**: roll back if goes badly? At what cost? One-way doors (DB migrations, breaking API changes, customer-visible names)?
+   *Why: shape rollout + feature-flag scope.*
+
+After interview: read back load-bearing decisions in one paragraph (problem, customer, hypothesis or known-requirement framing, primary use cases, key states, hard deadlines, biggest risk). Ask *"anything I got wrong before I draft?"*. Only after explicit confirmation, write to disk.
+
+## Spec structure (fixed)
+
+Use these sections in order. No new top-level sections. Skip only when genuinely doesn't apply (rare).
+
+```markdown
+# {Feature Name} — Spec
+
+## 1. Business Context
+The why. Customer, problem, cost of doing nothing, stakeholder pressure. Plain prose, 5–15 lines. Cite numbers when given; mark estimates as estimates.
+
+## 2. Hypothesis (to be validated)
+Falsifiable: "if we do X, we expect Y to improve by Z within T". Known requirement instead? Say so: "Not a hypothesis — known requirement driven by {reason}". Don't skip; framing matters.
+
+## 3. Objectives (and how to validate Hypothesis)
+Numbered. For each:
+- Metric or signal that proves it.
+- Data source.
+- Threshold or direction of change.
+- Timeframe to evaluate.
+- Kill criterion (if hypothesis-mode): what counts as failed + what we do.
+
+Known-requirement: replace "validate hypothesis" with "definition of done" — still concrete + measurable.
+
+## 4. Decisions
+Resolved questions go here. Ambiguous → **Open questions** section.
+
+### 4.1 Use-cases
+Numbered. Each: actor, trigger, flow (2–6 numbered steps), outcome.
+
+### 4.2 State transitions & edge cases
+- State machine if any (lifecycle states, allowed/forbidden transitions).
+- Edge cases from interview, each with decided handling.
+- Idempotency rule.
+- Concurrency rule.
+- Time-bounded rules (TTL, expiry, soak windows).
+
+### 4.3 Acceptance scenarios
+3–7 Given/When/Then. Minimum: happy, error, edge, integration-driven (when applicable). Become plan's test matrix.
+
+### 4.4 Negative scope
+Bulleted, one-line reason each: deferred to v2 (link if exists), unrelated workflow, hands-off contract. Be petty.
+
+## 5. Alternatives considered (optional)
+Each: short paragraph, what it was, why rejected. None? Say so: "Alternatives considered: none — only viable path because {reason}." Don't omit silently.
+
+## 6. Open questions
+Each: question, recommended default, who can answer, what unblocks if answered.
+
+## 7. Risks assumed
+Bulleted. Each: risk, assumption (which if violated makes risk real), mitigation (or "accepted, no mitigation — see **Open questions**"), rough likelihood/severity (low/medium/high).
+```
+
+## Filename + date
+
+`ai-plans/YYYY-MM-DD-FEATURE_NAME_SPEC.md`. Today's date ISO. `FEATURE_NAME` `UPPERCASE_WITH_UNDERSCORES`. Matching plan file use same prefix with `_IMPLEMENTATION_PLAN.md` so spec/plan pair groupable in `ls`.
+
+## Style rules
+
+- **Plain English over jargon.** Read by product, design, sales engineering, on-call. Acronyms expanded on first use.
+- **No code.** No SQL, migration snippets, class skeletons, JSON contracts beyond what customer literally agreed to. Code lives in plan. Exception: typed interface client team committed to (Bookmarks spec's `IBookmarkBarFolderItem` TypeScript) belongs in **Decisions → Use-cases** or **Decisions → Acceptance scenarios** — as literal contract, not implementation guidance.
+- **No file paths or app names.** "We'll add this to `core/sales/models/order.py`" plan-level.
+- **No estimates.** Sizing belongs in plan.
+- **No marketing language.** "Seamlessly", "robust", "best-in-class", "delightful" — strike.
+- **Decisions decided; assumptions flagged.** Solid-feeling but unverified → move to **Open questions** or **Risks assumed**.
+- **One feature per spec.** Multiple loosely-coupled features → multiple specs.
+- **Illustrate with examples + diagrams, not prose.** "For example, if tenant admin clicks 'Add tag' button on order details page, then..." better than "tenant admins should be able to add tags to orders in UI". State machine diagram better than "orders have lifecycle states: Draft, Active, Archived". Diagrams must use mermaidjs syntax to ensure stay up to date with reality.
+
+## Will not
+
+- **Generate spec from one-liner without interviewing.** Even with 200 words pasted, interview still runs. Only override is explicit *"just write the spec, I'll fix it"*; then every assumption goes in **Open questions** or **Risks assumed**.
+- **Use existing spec files in `ai-plans/` as structural templates.** Prior-art prompts, not specs in this skill's form. Read only if user explicitly asks.
+- **Pre-decide implementation strategy.** Storage shape, partitioning, API surface, feature-flag mechanics — plan-level. Spec stops at "what" + "why".
+- **Skip Open questions when real unknowns exist.** Spec with no open questions on non-trivial feature suspicious.
+- **Pretty up rough thinking.** "I dunno, maybe we add tags" → don't paraphrase as "to enable tenants to enrich order metadata for downstream routing decisions". Either ask for the why or quote them: "Stated motivation: 'I dunno, maybe we add tags' — see **Open questions**, item 1."
+- **Never use `§N` shorthand for section references.** Use section names verbatim — `Business Context`, `Hypothesis`, `Objectives`, `Decisions`, `Decisions → Use-cases`, `Decisions → Acceptance scenarios`, `Decisions → Negative scope`, `Alternatives considered`, `Open questions`, `Risks assumed`. `§4.3` makes the reader count headings and breaks when the spec evolves.
+
+## Checklist
+
+- [ ] Step 0 interview run; load-bearing decisions echoed back; user confirmed before drafting.
+- [ ] Filename: `ai-plans/{YYYY-MM-DD}-{FEATURE_NAME}_SPEC.md`.
+- [ ] All seven sections in order.
+- [ ] **Business Context** cites stakeholders + rough cost-of-doing-nothing.
+- [ ] **Hypothesis** falsifiable — or known-requirement with driver named. Not silently both.
+- [ ] **Objectives** has metric, source, threshold, timeframe, kill criterion (when hypothesis-mode).
+- [ ] **Decisions → Use-cases** each: actor + trigger + step-by-step flow + outcome.
+- [ ] **Decisions → State transitions & edge cases** covers state machine, edge cases, idempotency, concurrency, time-bounded rules where applicable.
+- [ ] **Decisions → Acceptance scenarios** has 3–7 scenarios covering happy / error / edge / integration paths.
+- [ ] **Decisions → Negative scope** exhaustive enough to surprise user.
+- [ ] **Alternatives considered** present (or explicit "none" with reason).
+- [ ] **Open questions** lists every unresolved item with default, owner, unblocks-on.
+- [ ] **Risks assumed** has assumption + mitigation + likelihood/severity.
+- [ ] Body has no code, no file paths, no app names, no time estimates, no marketing language.
+- [ ] Every unverified inference in **Open questions** or **Risks assumed** — not in **Business Context** through **Decisions**.
+- [ ] No `§N` section references anywhere in the spec body. Use section names.

package/skills/vinta-derive-skills/resources/foundation-skills/open-pr-from-context/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: open-pr-from-context
+description: Publish one `.vinta-ai-workflows/prs-context/{feature-name}/{phase-name}.md` file as a real PR + inline review comments by invoking the bundled [open-pr.sh](scripts/open-pr.sh) shell script. The script handles all parsing + CLI calls (`gh` for GitHub, `glab` for GitLab); this skill is a thin wrapper that picks the file, runs the script, and reports the result. Use after `implement-plan` has pushed a phase branch + written the context file, or any time afterwards to publish a `status: pending` file. Does nothing else — no diff editing, no extra checks, no skill-side parsing.
+---
+
+# Open PR from context
+
+[implement-plan](../implement-plan/SKILL.md) writes per-phase PR drafts to `.vinta-ai-workflows/prs-context/{feature-name}/{phase-name}.md` ([template](../../prs-context-template.md)) and (when a PR CLI is detected) calls this skill to publish them. When the runtime had no PR CLI at write time, the file sits as `status: pending` until someone runs this skill in an environment with the CLI.
+
+The mechanical work — parse frontmatter, detect CLI, open PR, post each inline comment, rewrite frontmatter to `published`, append publish log — lives in [`scripts/open-pr.sh`](scripts/open-pr.sh). This SKILL.md just wires the agent to it.
+
+## Dependencies
+
+The script needs: `bash 4+`, `git`, `yq` (Mike Farah's), `jq`, and one of `gh` / `glab`. Install via the project's package manager / Homebrew / apt:
+
+- macOS: `brew install yq jq gh` (or `glab`).
+- Debian/Ubuntu: `apt install yq jq` + `gh` from cli.github.com (or `glab` from gitlab.com).
+- Inside CI runners: ensure these are present in the image.
+
+The script bails early with `missing dependency: <name>` if any are absent. Surface the install command — don't auto-install.
+
+## Steps
+
+### 1. Pick the file
+
+If the user passed a file path → use it.
+
+Otherwise list candidates: `find .vinta-ai-workflows/prs-context -type f -name '*.md'`, read each one's frontmatter `status` field, prefer `status: pending`. Use `AskUserQuestion` to confirm if more than one is pending.
+
+### 2. Run the script
+
+```bash
+bash ai-tools/skills/open-pr-from-context/scripts/open-pr.sh <file>
+```
+
+(The script has the executable bit set, so `./ai-tools/skills/open-pr-from-context/scripts/open-pr.sh <file>` also works.)
+
+Optional flags:
+
+- `--cli gh|glab` — force a specific PR CLI. Default: auto-detect (`gh` first, then `glab`).
+- `--dry-run` / `-n` — print what would be posted; touch nothing remote and don't rewrite the file.
+
+Pass through whatever the user explicitly asked for; otherwise no flags.
+
+### 3. Report the result
+
+Read the script's stdout + exit code:
+
+- **Exit 0** — PR opened (or pre-existing detected); all comments posted. File rewritten to `status: published` + `pr_url`. Surface the URL to the user; you're done.
+- **Exit 1** — PR opened, but one or more inline comments failed. The script's stderr lists which `(file:line)` failed. Forward the failures verbatim. Most common cause: a force-push between branch push and now invalidated the line position — re-run after pushing.
+- **Exit 2** — Hard failure (file invalid, branch not pushed, CLI missing/unauthed, missing dependency). Forward the script's error message; do **not** improvise (don't push the branch, don't install CLIs, don't auth on the user's behalf).
+
+## Inputs the script expects
+
+The bundled [prs-context-template.md](../../prs-context-template.md) documents the file shape. The script verifies:
+
+- Frontmatter: `branch`, `base` (required); `status`, `pr_url` (read + written).
+- `# Title` section: single line, non-empty.
+- `# Description` section: markdown, non-empty.
+- `# Comments` section: a single fenced ```yaml list (may be empty — clean phases are valid).
+
+A file at `status: published` with a populated `pr_url` is a no-op — the script prints the URL and exits 0 without touching anything.
+
+## What this skill / script do NOT do
+
+- **Do not push the branch.** `implement-plan` already pushed it. If the script reports `branch not pushed`, that's a setup bug — surface it.
+- **Do not edit the diff.** Comment placement is informational only.
+- **Do not re-run tests / lint.** Those happened in `implement-plan` before push.
+- **Do not draft new descriptions or comments.** The file is the source of truth — edit the file (or re-run `implement-plan` for that phase) before re-invoking.
+- **Do not install or authenticate CLIs.** Surfaces the gap, stops.
+- **Do not delete the PR-context file.** `implement-plan` cleans up at plan end; until then the file is durable history.
+
+## Pitfalls
+
+- **Stacked phases.** PR base is the previous phase's branch, not `main`. The file's `base` field has the right value; the script trusts it. Don't override.
+- **Force-pushed branch.** Inline comments target a SHA. If the branch was force-pushed between PR open and comment posting, GitHub/GitLab may reject specific lines as "no longer in the diff". Per-comment failures are reported but don't abort the run — the surviving comments still post. Re-run after pushing if you want the failed ones.
+- **Empty `# Comments`.** Valid; clean phases produce few or zero comments. Script no-ops the comment loop, still rewrites status to `published`.
+- **Missing `yq` / `jq`.** Script bails with `missing dependency: yq` (or `jq`) before doing anything. Install the missing tool, re-run.