@yaawn/workflow 0.3.1 → 0.5.0

package/agents/skills/yaawn-implement-plan/scripts/worktrees.ts

@@ -1,19 +1,25 @@
 import { execFile, execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
 import path from "node:path";
 import { promisify } from "node:util";
 import { uncommittedChangesAsync } from "./targets.js";
 
 // Shared by yaawn-implement-plan (creates one git worktree per issue) and
-// yaawn-verify-executed-plan (checks it verifies in the issue's worktree).
+// yaawn-verify-executed-plan (resolves the issue's worktree to verify in).
 //
 // Layout: the project root holds a bare `.git` repository, the main working
 // copy is a normal checkout at `<project>/main`, and every issue worktree is
-// a sibling of it at `<project>/yaawn-<issue>-<slug>`.
+// a sibling of it at `<project>/yaawn-<issue>-<slug>`. A prototype issue
+// (labelled `Yaawn: Prototype`) gets its worktree at
+// `<project>/prototype/yaawn-<issue>-<slug>` on branch
+// `prototype/yaawn-<issue>-<slug>`, which is never merged.
 
 export type WorktreeCheckStatus = "ok" | "warn" | "fail";
 
+// `path` is the worktree to verify in; null only when the check fails.
 export interface WorktreeCheck {
   status: WorktreeCheckStatus;
+  path: string | null;
   message: string;
 }
 
@@ -21,16 +27,20 @@ export interface WorktreeLayout {
   issue: number;
   mainCopy: string;
   registered: Iterable<string>;
-  currentToplevel: string;
-  // Resolved by branch (yaawn/<issue>), not by the title slug — the slug in
-  // the directory name is for humans only.
+  // Resolved by branch (yaawn/<issue>, or prototype/yaawn-<issue>-*), not by
+  // the title-derived path.
   ownWorktree?: string | null;
+  locked?: Iterable<string>;
+  // Registered, but git marks them prunable or their directory is gone.
+  stale?: Iterable<string>;
 }
 
 export interface WorktreeEntry {
   path: string;
   branch: string | null;
   bare: boolean;
+  locked: boolean;
+  prunable: boolean;
 }
 
 export interface AheadBehind {
@@ -58,12 +68,14 @@ const branchPrefix = "branch refs/heads/";
 const maxSlugLength = 40;
 const fallbackMainCopyName = "main";
 const fallbackDefaultBranches = ["main", "master"];
+const prototypeDir = "prototype";
+const fallbackPrototypeSlug = "prototype";
+
+export const prototypeLabel = "Yaawn: Prototype";
 
 const aheadBehindPattern = /^(\d+)\s+(\d+)$/;
 const execFileAsync = promisify(execFile);
 
-export const branchName = (issue: number): string => `yaawn/${issue}`;
-
 export function git(args: string[]): string {
   return execFileSync("git", args, {
     encoding: "utf-8",
@@ -92,9 +104,37 @@ export function titleSlug(title: string): string {
     .replace(/-+$/, "");
 }
 
-export function worktreeName(issue: number, title: string): string {
+// Exact label-name match only: a look-alike label never makes a prototype.
+export const isPrototype = (labels: readonly string[]): boolean =>
+  labels.includes(prototypeLabel);
+
+// A prototype branch always carries a slug, so `prototype/yaawn-<issue>-*`
+// finds it.
+const prototypeSlug = (title: string): string =>
+  titleSlug(title) || fallbackPrototypeSlug;
+
+export function prototypeBranchPrefix(issue: number): string {
   assertIssueNumber(issue);
-  const slug = titleSlug(title);
+  return `${prototypeDir}/yaawn-${issue}-`;
+}
+
+export function branchName(
+  issue: number,
+  labels: readonly string[] = [],
+  title = "",
+): string {
+  return isPrototype(labels)
+    ? `${prototypeBranchPrefix(issue)}${prototypeSlug(title)}`
+    : `yaawn/${issue}`;
+}
+
+export function worktreeName(
+  issue: number,
+  title: string,
+  labels: readonly string[] = [],
+): string {
+  assertIssueNumber(issue);
+  const slug = isPrototype(labels) ? prototypeSlug(title) : titleSlug(title);
   return slug ? `yaawn-${issue}-${slug}` : `yaawn-${issue}`;
 }
 
@@ -109,6 +149,8 @@ function entryFromBlock(lines: string[]): WorktreeEntry | null {
     branch:
       branchLine === undefined ? null : branchLine.slice(branchPrefix.length),
     bare: lines.includes("bare"),
+    locked: lines.some((line) => line === "locked" || line.startsWith("locked ")),
+    prunable: lines.some((line) => line === "prunable" || line.startsWith("prunable ")),
   };
 }
 
@@ -163,12 +205,56 @@ export function branchWorktreeFromPorcelain(
   return checkout?.path ?? null;
 }
 
+// A prototype's checkout on any `prototype/yaawn-<issue>-*` branch counts, so
+// a relaunch resumes it even after the issue was renamed.
+export function issueWorktreeFromPorcelain(
+  porcelain: string,
+  issue: number,
+  labels: readonly string[] = [],
+  title = "",
+): string | null {
+  const exact = branchWorktreeFromPorcelain(
+    porcelain,
+    branchName(issue, labels, title),
+  );
+  if (exact !== null || !isPrototype(labels)) return exact;
+  const prefix = prototypeBranchPrefix(issue);
+  const checkout = entriesFromPorcelain(porcelain).find(
+    (entry) => !entry.bare && entry.branch?.startsWith(prefix) === true,
+  );
+  return checkout?.path ?? null;
+}
+
+// Both the worktree path and its actual branch, so a relaunch after a
+// rename keeps reporting the branch that is really checked out.
+export function issueWorktreeAndBranchFromPorcelain(
+  porcelain: string,
+  issue: number,
+  labels: readonly string[] = [],
+  title = "",
+): { path: string; branch: string } | null {
+  const entry = entriesFromPorcelain(porcelain).find((candidate) => {
+    if (candidate.bare || candidate.branch === null) return false;
+    if (candidate.branch === branchName(issue, labels, title)) return true;
+    return (
+      isPrototype(labels) &&
+      candidate.branch.startsWith(prototypeBranchPrefix(issue))
+    );
+  });
+  if (entry === undefined || entry.branch === null) return null;
+  return { path: entry.path, branch: entry.branch };
+}
+
 export function worktreePathFor(
   projectRoot: string,
   issue: number,
   title: string,
+  labels: readonly string[] = [],
 ): string {
-  return path.join(projectRoot, worktreeName(issue, title));
+  const name = worktreeName(issue, title, labels);
+  return isPrototype(labels)
+    ? path.join(projectRoot, prototypeDir, name)
+    : path.join(projectRoot, name);
 }
 
 // --- git
@@ -209,22 +295,58 @@ export function usesBareLayout(): boolean {
   return isBareLayout(listPorcelain());
 }
 
-export function worktreePath(issue: number, title: string): string {
+export function worktreePath(
+  issue: number,
+  title: string,
+  labels: readonly string[] = [],
+): string {
   return worktreePathFor(
     projectRootFromPorcelain(listPorcelain()),
     issue,
     title,
+    labels,
   );
 }
 
 // The branch's existing checkout wins over the title-derived path, so a
 // relaunch resumes the earlier worktree even after the issue was renamed.
-export function laneWorktreePath(issue: number, title: string): string {
+export function laneWorktreePath(
+  issue: number,
+  title: string,
+  labels: readonly string[] = [],
+): string {
   const porcelain = listPorcelain();
   return (
-    branchWorktreeFromPorcelain(porcelain, branchName(issue)) ??
-    worktreePathFor(projectRootFromPorcelain(porcelain), issue, title)
+    issueWorktreeFromPorcelain(porcelain, issue, labels, title) ??
+    worktreePathFor(projectRootFromPorcelain(porcelain), issue, title, labels)
+  );
+}
+
+// Resolves both the worktree path and branch for a lane: the existing
+// checkout's actual branch when the worktree is reused, otherwise the
+// title-derived values for a fresh worktree.
+export function laneWorktreeAndBranch(
+  issue: number,
+  title: string,
+  labels: readonly string[] = [],
+): { path: string; branch: string } {
+  const porcelain = listPorcelain();
+  const existing = issueWorktreeAndBranchFromPorcelain(
+    porcelain,
+    issue,
+    labels,
+    title,
   );
+  if (existing !== null) return existing;
+  return {
+    path: worktreePathFor(
+      projectRootFromPorcelain(porcelain),
+      issue,
+      title,
+      labels,
+    ),
+    branch: branchName(issue, labels, title),
+  };
 }
 
 export function registeredWorktrees(): Set<string> {
@@ -236,58 +358,96 @@ const normalized = (worktree: string): string => path.resolve(worktree);
 const samePath = (left: string, right: string): boolean =>
   normalized(left) === normalized(right);
 
-export function runsInOwnWorktree(issue: number, title: string): boolean {
-  return samePath(worktreePath(issue, title), currentToplevel());
+export function runsInOwnWorktree(
+  issue: number,
+  title: string,
+  labels: readonly string[] = [],
+): boolean {
+  return samePath(worktreePath(issue, title, labels), currentToplevel());
 }
 
 // --- classification
 
-function checkOwnWorktree(own: string, toplevel: string): WorktreeCheck {
-  return samePath(own, toplevel)
-    ? { status: "ok", message: `verifying in the issue's worktree ${own}` }
-    : {
-        status: "fail",
-        message: `run verification in the issue's worktree ${own}, not in ${toplevel}`,
-      };
+const includesPath = (paths: Iterable<string> = [], target: string): boolean =>
+  [...paths].some((candidate) => samePath(candidate, target));
+
+const failedCheck = (message: string): WorktreeCheck => ({
+  status: "fail",
+  path: null,
+  message,
+});
+
+function checkOwnWorktree(layout: WorktreeLayout, own: string): WorktreeCheck {
+  const { issue, locked, stale } = layout;
+  if (includesPath(stale, own)) {
+    return failedCheck(
+      `#${issue}'s worktree ${own} is stale — its directory is missing; restore it or run \`git worktree prune\``,
+    );
+  }
+  if (includesPath(locked, own)) {
+    return failedCheck(
+      `#${issue}'s worktree ${own} is locked — unlock it with \`git worktree unlock\` first`,
+    );
+  }
+  return { status: "ok", path: own, message: `verifying in the issue's worktree ${own}` };
 }
 
-function checkMainCopy(
-  issue: number,
-  mainCopy: string,
-  toplevel: string,
-): WorktreeCheck {
-  return samePath(mainCopy, toplevel)
-    ? {
-        status: "warn",
-        message: `#${issue} has no git worktree of its own — verifying the main copy`,
-      }
-    : {
-        status: "fail",
-        message: `#${issue} has no git worktree of its own — run verification in the main copy ${mainCopy}, not in ${toplevel}`,
-      };
+function checkMainCopy(layout: WorktreeLayout): WorktreeCheck {
+  const { issue, mainCopy, registered, stale } = layout;
+  if (!includesPath(registered, mainCopy) || includesPath(stale, mainCopy)) {
+    return failedCheck(
+      `#${issue} has no git worktree of its own, and the main copy ${mainCopy} is missing`,
+    );
+  }
+  return {
+    status: "warn",
+    path: mainCopy,
+    message: `#${issue} has no git worktree of its own — verifying the main copy`,
+  };
 }
 
+// Resolves where to verify, wherever the session runs.
 export function classifyWorktree(layout: WorktreeLayout): WorktreeCheck {
-  const { issue, mainCopy, registered, ownWorktree, currentToplevel } = layout;
-  const own =
-    ownWorktree != null &&
-    [...registered].some((worktree) => samePath(worktree, ownWorktree))
-      ? ownWorktree
-      : null;
-  return own !== null
-    ? checkOwnWorktree(own, currentToplevel)
-    : checkMainCopy(issue, mainCopy, currentToplevel);
+  const { registered, ownWorktree } = layout;
+  return ownWorktree != null && includesPath(registered, ownWorktree)
+    ? checkOwnWorktree(layout, ownWorktree)
+    : checkMainCopy(layout);
+}
+
+function staleWorktrees(entries: WorktreeEntry[]): string[] {
+  return entries
+    .filter((entry) => entry.prunable || !existsSync(entry.path))
+    .map((entry) => entry.path);
 }
 
-export function checkWorktree(issue: number): WorktreeCheck {
+function layoutFromGit(
+  issue: number,
+  labels: readonly string[],
+  title: string,
+): WorktreeLayout {
   const porcelain = listPorcelain();
-  return classifyWorktree({
+  const entries = entriesFromPorcelain(porcelain);
+  return {
     issue,
     mainCopy: mainCopyFromPorcelain(porcelain, defaultBranches()),
-    registered: worktreesFromPorcelain(porcelain),
-    currentToplevel: currentToplevel(),
-    ownWorktree: branchWorktreeFromPorcelain(porcelain, branchName(issue)),
-  });
+    registered: entries.map((entry) => entry.path),
+    ownWorktree: issueWorktreeFromPorcelain(porcelain, issue, labels, title),
+    locked: entries.filter((entry) => entry.locked).map((entry) => entry.path),
+    stale: staleWorktrees(entries),
+  };
+}
+
+// Never throws: a git failure becomes a failed check.
+export function checkWorktree(
+  issue: number,
+  labels: readonly string[] = [],
+  title = "",
+): WorktreeCheck {
+  try {
+    return classifyWorktree(layoutFromGit(issue, labels, title));
+  } catch (error) {
+    return failedCheck(`could not resolve the worktree: ${gitErrorReason(error)}`);
+  }
 }
 
 // --- main copy sync
@@ -338,6 +498,13 @@ function redactedGitError(error: unknown): string {
   return line ? `: ${line.replace(/\/\/[^/\s@]+@/g, "//***@")}` : "";
 }
 
+function gitErrorReason(error: unknown): string {
+  const stderr = redactedGitError(error);
+  if (stderr) return stderr.slice(": ".length);
+  const message = error instanceof Error ? error.message : String(error);
+  return message.split("\n")[0];
+}
+
 // Never waits for a credential prompt: an unattended launch would hang.
 async function gitAsync(args: string[]): Promise<string> {
   const { stdout } = await execFileAsync("git", args, {

package/agents/skills/yaawn-prepare-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yaawn-prepare-plan
-description: "Turn a new idea or an existing GitHub issue into an approved work item — a story, refactor, spike, bug report, or other change — pick or confirm its type, draft or reconsider it, grill it, and save it to the issue — ready for /yaawn-create-plan (spikes go to a human instead). Use when: preparing work for planning, new idea, refine issue #N, write and grill a story, write a refactor, write a spike, write a bug report, write an other change, check if a story needs splitting, get a work item ready for planning."
+description: "Turn a new idea or an existing GitHub issue into an approved work item — a story, refactor, spike, bug report, prototype, or other change — pick or confirm its type, draft or reconsider it, grill it, and save it to the issue — ready for /yaawn-create-plan (spikes go to a human instead). Use when: preparing work for planning, new idea, refine issue #N, write and grill a story, write a refactor, write a spike, write a bug report, write a prototype, write an other change, check if a story needs splitting, get a work item ready for planning."
 argument-hint: "[<issue>]"
 disable-model-invocation: true
 metadata:
@@ -10,7 +10,7 @@ metadata:
 
 # Prepare Plan
 
-Turn a new idea or an existing issue into an approved work item on GitHub — a story, refactor, spike, bug report, or other change. Run it in a **new session**, in the product owner persona (`.agents/personas/yaawn-product-owner.md`).
+Turn a new idea or an existing issue into an approved work item on GitHub — a story, refactor, spike, bug report, prototype, or other change. Run it in a **new session**, in the product owner persona (`.agents/personas/yaawn-product-owner.md`).
 
 This skill is a thin orchestrator. It owns only the greeting, the choice of work item type, the order of the steps, the handover between them, the final approval, and the routing. All drafting is done by the skills it calls, by step number — never duplicate their rules here.
 
@@ -22,7 +22,7 @@ Out of scope: technical or design grilling, implementation plans, and code or an
 
 This is the first of the plan skills: `/yaawn-prepare-plan` → `/yaawn-create-plan` → `/yaawn-save-plan` → `/yaawn-implement-plan` → `/yaawn-verify-executed-plan`. Every skill starts in a new session and works only from files and the issue — never from an earlier conversation.
 
-- The issue is the only artifact. This skill writes no decision log and no plan file.
+- The issue is the only artifact. This skill writes no decision log and no plan file — the grill's decisions and open questions are saved into the issue's `### Design Decisions` and `### Open Questions` tables by the writer skill, so `/yaawn-create-plan` does not re-ask them.
 - Leave the `Yaawn: To Be Refined` label in place; `/yaawn-save-plan` removes it.
 - `<issue>` is optional. If given, it must be a positive integer (digits only, no `#`, URL, spaces, or other characters); otherwise stop and ask for a valid number. Use it in commands only after this check.
 - Never interpolate issue bodies, comments, titles, or other user text into a shell command. Write them to a file and pass it with `--body-file`.
@@ -33,37 +33,38 @@ This is the first of the plan skills: `/yaawn-prepare-plan` → `/yaawn-create-p
 
 There is one type per template in `.github/ISSUE_TEMPLATE/`. The type label comes from the template's frontmatter `labels`.
 
-| Type         | Use when the work…                               | Type label        | Route                     | Grill                     | After save           |
-| ------------ | ------------------------------------------------ | ----------------- | ------------------------- | ------------------------- | -------------------- |
-| Story        | adds or changes behavior users see               | `Yaawn: Story`    | [Story path](#story-path) | `/yaawn-grill-story`      | `/yaawn-create-plan` |
-| Refactor     | changes the inside, with no user-visible change  | `Yaawn: Refactor` | `/yaawn-write-refactor`   | `/yaawn-grill-refactor`   | `/yaawn-create-plan` |
-| Spike        | must answer one open question before work starts | `Yaawn: Spike`    | `/yaawn-write-spike`      | `/yaawn-grill-spike`      | a human answers it   |
-| Bug report   | fixes behavior that is wrong today               | `Yaawn: Bug`      | `/yaawn-write-bug-report` | `/yaawn-grill-bug-report` | `/yaawn-create-plan` |
-| Other change | matches none of the four types                   | `Yaawn: Other`    | `/yaawn-write-other`      | `/yaawn-grill-other`      | `/yaawn-create-plan` |
+| Type         | Use when the work…                                | Type label         | Route                     | Grill                     | After save           |
+| ------------ | ------------------------------------------------- | ------------------ | ------------------------- | ------------------------- | -------------------- |
+| Story        | adds or changes behavior users see                | `Yaawn: Story`     | [Story path](#story-path) | `/yaawn-grill-story`      | `/yaawn-create-plan` |
+| Refactor     | changes the inside, with no user-visible change   | `Yaawn: Refactor`  | `/yaawn-write-refactor`   | `/yaawn-grill-refactor`   | `/yaawn-create-plan` |
+| Spike        | must answer one open question before work starts  | `Yaawn: Spike`     | `/yaawn-write-spike`      | `/yaawn-grill-spike`      | a human answers it   |
+| Bug report   | fixes behavior that is wrong today                | `Yaawn: Bug`       | `/yaawn-write-bug-report` | `/yaawn-grill-bug-report` | `/yaawn-create-plan` |
+| Prototype    | builds a throwaway version to test with customers | `Yaawn: Prototype` | `/yaawn-write-prototype`  | `/yaawn-grill-prototype`  | `/yaawn-create-plan` |
+| Other change | matches none of the five types                    | `Yaawn: Other`     | `/yaawn-write-other`      | `/yaawn-grill-other`      | `/yaawn-create-plan` |
 
 ## 1. Greet and choose the type
 
-- **New idea (no `<issue>`):** greet the user and offer the five types through the ask tool, each with its one-line "use when", plus a last option: **"Not sure / none of these"**.
+- **New idea (no `<issue>`):** greet the user and offer the six types through the ask tool, each with its one-line "use when" — for a prototype: "Prototype — build a throwaway version of a feature idea to test with customers and learn what works" — plus a last option: **"Not sure / none of these"**.
 - **Existing issue:** read it with `gh issue view <issue> --json title,body,labels,comments`. Infer the type from its type label (table above) and ask the user to confirm it.
   - **Confirmed:** continue with that type.
   - **Override:** warn that re-typing rewrites the issue's body to the new type's template — the current body's sections are replaced — and ask for explicit confirmation. Only after it, continue with the new type; content worth keeping is carried over only with the user's agreement. Without confirmation, keep the inferred type.
   - **No type label:** fall back to the picker, as for a new idea.
-- **"Not sure / none of these":** help find the right shape — ask what the work changes: behavior users see (story), the inside without user-visible change (refactor), wrong behavior today (bug report), or nothing yet because a question must be answered first (spike). Offer the matching type. If nothing fits, offer **other change** as the last resort; if the user declines it too, say so and stop — never save anything on this path.
+- **"Not sure / none of these":** help find the right shape — ask what the work changes: behavior users see (story), the inside without user-visible change (refactor), wrong behavior today (bug report), nothing yet because a question must be answered first (spike), or a throwaway version of a feature idea to test with customers before committing to it (prototype). Offer the matching type. If nothing fits, offer **other change** as the last resort; if the user declines it too, say so and stop — never save anything on this path.
 
 If a writer skill later finds the item is a different type (for example a refactor that changes user-visible behavior), return here and re-offer the type choice.
 
 ## 2. Route
 
 - **Story:** follow the [Story path](#story-path). For a confirmed re-type, tell `/yaawn-write-user-story` to draft the body from the story template as for a new story, and swap the type label after the save as in [Writer path](#writer-path) step 3.
-- **Refactor, spike, bug report, other change:** follow the [Writer path](#writer-path) with the routed writer and grill skills from the table.
+- **Refactor, spike, bug report, prototype, other change:** follow the [Writer path](#writer-path) with the routed writer and grill skills from the table.
 
 ## Writer path
 
-1. **Draft, grill, check:** run step 1 of the routed writer skill (draft or refine), then the routed type's `/yaawn-grill-*` skill from the table — tell it to skip its scope check and that this skill defines what happens when the grill ends: continue with the writer's step 3 (quality check). The grill replaces the writer's step 2 (light grill) in this session only. For an existing issue, the writer reads the issue itself; for a confirmed re-type, tell it to build the body from its own template as for a new issue.
-2. **Approve:** present the finished fields and ask the user to approve them through the ask tool. Wait for it — never create or edit the issue before.
-3. **Save:** run the writer's step 4 ("Saving the issue"). Tell it this approval is the one its saving step 1 asks for — do not ask again. It reads the template frontmatter and saves with `--body-file`. For a confirmed re-type, also swap the old type label for the new one: `gh issue edit <issue> --remove-label "<old type label>" --add-label "<new type label>"`, with both labels taken from the template frontmatters.
+1. **Draft, grill, check:** run step 1 of the routed writer skill (draft or refine), then the routed type's `/yaawn-grill-*` skill from the table — tell it to skip its scope check and that this skill defines what happens when the grill ends: continue with the writer's step 3 (quality check). The grill replaces the writer's step 2 (light grill) in this session only. When the grill ends, keep the `## Decisions` and `## Open questions` sections from its Result for the save. For an existing issue, the writer reads the issue itself; for a confirmed re-type, tell it to build the body from its own template as for a new issue.
+2. **Approve:** present the finished fields, together with the grill's decisions and open questions, and ask the user to approve them through the ask tool. Wait for it — never create or edit the issue before.
+3. **Save:** run the writer's step 4 ("Approve and save"), which follows its "Saving the issue". Tell it this approval is the one its saving step 1 asks for — do not ask again. Pass it the grill's `## Decisions` and `## Open questions` sections as they are, so it fills the issue's `### Design Decisions` and `### Open Questions` tables in the same save — except for a spike, whose template has neither table, so nothing is passed. It reads the template frontmatter and saves with `--body-file`. For a confirmed re-type, also swap the old type label for the new one: `gh issue edit <issue> --remove-label "<old type label>" --add-label "<new type label>"`, with both labels taken from the template frontmatters.
 4. **Hand off:**
-   - **Refactor, bug report, other change:** tell the user to start a **new session** and run `/yaawn-create-plan <issue>` there.
+   - **Refactor, bug report, prototype, other change:** tell the user to start a **new session** and run `/yaawn-create-plan <issue>` there. For a prototype, add that it is built on a never-merged `prototype/` branch and that `/yaawn-extract-learnings <issue>` replaces `/yaawn-verify-executed-plan` after `/yaawn-implement-plan`.
    - **Spike:** the session ends here — a human answers the spike. There is no handoff to `/yaawn-create-plan`; tell the user so.
 
 ## Story path
@@ -97,7 +98,7 @@ Then, in this session:
 
 ### 4. Grill the story
 
-Run `/yaawn-grill-story` on the story. Tell it to skip its scope check — the sprint-fit check or the split assessment already covered scope — and that this skill defines what happens when the grill ends: continue with step 5.
+Run `/yaawn-grill-story` on the story. Tell it to skip its scope check — the sprint-fit check or the split assessment already covered scope — and that this skill defines what happens when the grill ends: continue with step 5. Keep the `## Decisions` and `## Open questions` sections from its Result for step 6.
 
 ### 5. Quality check
 
@@ -105,6 +106,6 @@ Run the quality check from `/yaawn-write-user-story` step 6 on the grilled story
 
 ### 6. Approve and save
 
-Ask the user to approve the finished story, then create or update the issue with `/yaawn-write-user-story` step 8. Leave the `Yaawn: To Be Refined` label in place.
+Ask the user to approve the finished story, together with the grill's decisions and open questions, then create or update the issue with `/yaawn-write-user-story` step 8. Pass it the grill's `## Decisions` and `## Open questions` sections as they are, so it fills the issue's `### Design Decisions` and `### Open Questions` tables in the same save. Leave the `Yaawn: To Be Refined` label in place.
 
 End by telling the user to start a **new session** and run `/yaawn-create-plan <issue>` there.

package/agents/skills/yaawn-save-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yaawn-save-plan
-description: "Save the plan /yaawn-create-plan wrote to .yaawn/plans/yaawn-<issue>-plan.md into the GitHub issue's \"Implementation Plan\" section — open questions, design decisions, implementation steps, and an ELI5 Human Readable summary — and remove the Yaawn: To Be Refined label. Does not execute the plan (use yaawn-implement-plan) or verify it (use yaawn-verify-executed-plan)."
+description: "Save the plan /yaawn-create-plan wrote to .yaawn/plans/yaawn-<issue>-plan.md into the GitHub issue's \"Implementation Plan\" section — open questions, design decisions, implementation steps, and an ELI5 Human Readable summary — and remove the Yaawn: To Be Refined label. Offers to answer the plan's open questions with the user before saving. Does not execute the plan (use yaawn-implement-plan) or verify it (use yaawn-verify-executed-plan)."
 disable-model-invocation: true
 argument-hint: "[GitHub issue number]"
 metadata:
@@ -10,7 +10,7 @@ metadata:
 
 Start this skill in a new session. It works only from files and the issue, never from an earlier conversation: the plan is the file `/yaawn-create-plan` left at `.yaawn/plans/yaawn-<issue>-plan.md` in one of the project's git worktrees.
 
-Out of scope: changing the plan, grilling it again, and touching the story or acceptance criteria. To change the plan, run `/yaawn-create-plan` again.
+Out of scope: changing the plan beyond answering its open questions, grilling it again, and touching the story or acceptance criteria. To change the plan otherwise, run `/yaawn-create-plan` again.
 
 ## 1. Find the plan file
 
@@ -28,13 +28,32 @@ The plan file may live in another git worktree than the one this session runs in
 
 If no issue is given, the script infers it from the `yaawn-<issue>-plan.md` files in `.yaawn/plans/` of the current worktree, every `yaawn/<n>` worktree and the main copy together. Exactly one match: it is used. Several matches: the script lists them — ask which one. No match: ask for the issue number.
 
-## 2. Write the Human Readable summary
+## 2. Answer the open questions
+
+```sh
+npx tsx .agents/skills/yaawn-save-plan/scripts/save-plan.ts open-questions <issue>
+```
+
+The script prints the plan's `### Open Questions` rows whose Answer cell is empty — the questions `/yaawn-create-plan` left open, typically facts only the user knows (e.g. whether a feature flag exists in the flag provider).
+
+- `open questions: 0`: continue with step 3.
+- Otherwise ask the user through the ask tool (the ask-tool table and the option conventions are in [`.agents/yaawn-grilling.md`](../../yaawn-grilling.md)): the plan has N open questions — answer them now, before the save? Options: **Yes, one by one** and **No, save with them open**. If she declines, continue with step 3; the save still works, the issue just is not marked ready (step 5 reports why).
+- If she answers, go through the questions **one by one** in table order. For each, read the plan file and the issue for context, then ask through the ask tool with 2-4 possible answers, one marked as the recommendation in its description (e.g. "Recommended: ..."), keeping the free-text "Other" option available. Ground the suggestions in the plan's `### Design Decisions` and the issue — never invent facts. When the answer is a fact only the user knows, offer the plausible states (e.g. "Yes — created", "No — not yet", "Not needed") and recommend the one the plan's steps assume: a plan that lists "create the flag" as a manual step assumes it does not exist yet. Wait for each answer before asking the next; if she wants to leave a question open, omit it.
+- Write her answers to `.yaawn/plans/yaawn-<issue>-answers.json` in the current worktree — a JSON object mapping each question's `#` to her answer, e.g. `{ "1": "Yes — the flag exists", "2": "Redis" }`. Then run:
+
+```sh
+npx tsx .agents/skills/yaawn-save-plan/scripts/save-plan.ts answer <issue>
+```
+
+The script fills the Answer cells in the plan file (escaping `|` inside an answer), never overwrites an already-answered row, and deletes the answers file afterwards. An unknown question number means the plan changed since the questions were listed — list them again with `open-questions` and repeat. The answers live in the plan file, so the summary, preview, and save below pick them up.
+
+## 3. Write the Human Readable summary
 
 Read the plan file and write a **short** "Human Readable" version of it to the summary path step 1 printed — `.yaawn/plans/yaawn-<issue>-human-readable.md` next to the plan file, in the same worktree — following `.agents/output-styles/yaawn-eli5.instructions.md`. Write only the content — no `### Human Readable` heading; the script adds the content under the existing one. Inside the summary, use only `####` or deeper headings — never `#`, `##`, or `###`. The content lands inside the issue's `## Implementation Plan` section, and a shallower heading would restructure the template and truncate the plan `/yaawn-implement-plan` later extracts. The script demotes any heading that is too shallow, so the issue's heading structure never changes.
 
 Explain the **implementation only**. Do not explain the feature; what the user gets is already in the issue's story and acceptance criteria. If applicable, add a mermaid diagram showing the architecture of the plan. Keep the diagram on a conceptual, high level — it is meant to give an overview.
 
-## 3. Preview
+## 4. Preview
 
 ```sh
 npx tsx .agents/skills/yaawn-save-plan/scripts/save-plan.ts preview <issue>
@@ -43,10 +62,10 @@ npx tsx .agents/skills/yaawn-save-plan/scripts/save-plan.ts preview <issue>
 The script ([scripts/save-plan.ts](./scripts/save-plan.ts), with the section logic in [scripts/plan-body.ts](./scripts/plan-body.ts)) fetches the issue body fresh and builds the new body: it replaces the content under `### Human Readable`, `### Open Questions`, `### Design Decisions`, `### Files to Change`, and `### LLM Plan` inside `## Implementation Plan`. Each subsection is replaced as a whole block, so re-saving onto an older issue that still carries a `#### Definition of Done` section under `### LLM Plan` drops that stale copy as a side effect — the Definition of Done lives only in `.yaawn/yaawn-definition-of-done.md`. Headings inside the inserted content are demoted below `###`, so the inserted content can never change the issue's heading structure — and re-saving an issue whose plan section an older yaawn broke with `##`-level content repairs it. Nothing outside that section changes — the story and acceptance criteria are never touched. An issue without `## Implementation Plan` (created without a template) gets the section appended with all five subsections. An older issue whose `## Implementation Plan` lacks `### Files to Change` gets that heading inserted right before `### LLM Plan`. It prints whether the issue already has a plan and the diff of the body.
 
 - An error: report it and stop. Any other missing subsection heading means the issue's `## Implementation Plan` is incomplete — the user adds the heading, then runs this skill again.
-- `existing plan: no`: continue with step 4.
+- `existing plan: no`: continue with step 5.
 - `existing plan: yes`: summarize the diff in a few lines — which steps, decisions, and questions change — and ask **one** question through the ask tool: overwrite the plan on the issue? Do not grill or reconsider the plan here; the plan file is the reviewed result of `/yaawn-create-plan`. If the user declines, stop.
 
-## 4. Save
+## 5. Save
 
 ```sh
 npx tsx .agents/skills/yaawn-save-plan/scripts/save-plan.ts save <issue>
@@ -60,6 +79,6 @@ The issue body snapshots (`yaawn-<issue>-body-current.md`, `yaawn-<issue>-body.m
 
 Leave the working files under `.yaawn/plans/` in place — the developer cleans them up manually.
 
-## 5. Hand off
+## 6. Hand off
 
 Tell the user: once every issue that belongs in the run has a saved plan, start a new session and run `/yaawn-implement-plan <issue>`.