@pavp/storywright 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "storywright",
+  "version": "0.1.0",
+  "description": "PM skills for Claude Code — turn ambiguous inputs (prompts, screenshots, Figma links) into Jira-ready user stories.",
+  "author": "pavp",
+  "license": "MIT",
+  "homepage": "https://github.com/pavp/storywright",
+  "repository": "https://github.com/pavp/storywright",
+  "skills": [
+    "skills/story-generate",
+    "skills/story-refine",
+    "skills/story-split",
+    "skills/story-from-figma",
+    "skills/_components/clarification-questions",
+    "skills/_components/acceptance-criteria",
+    "skills/_components/invest-checklist",
+    "skills/_components/definition-of-done",
+    "skills/_components/business-rules",
+    "skills/_components/edge-cases",
+    "skills/_components/analytics-events",
+    "skills/_components/risks-and-dependencies",
+    "skills/_components/jira-wiki-formatter"
+  ],
+  "tags": ["product-management", "user-stories", "jira", "agile", "invest"]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Story Skills contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# storywright
+
+PM skills for Claude Code that turn ambiguous inputs — vague prompts, half-baked stories, screenshots, Figma links — into **Jira-ready user stories** with acceptance criteria, edge cases, risks, analytics, and Definition of Done.
+
+> Inspired by [`deanpeters/Product-Manager-Skills`](https://github.com/deanpeters/Product-Manager-Skills) (CC BY-NC-SA 4.0). Clean-room MIT rewrite — no copied content. Frontmatter shape, body skeleton, and splitting-pattern selection draw on patterns from that repo; prose, component taxonomy, dual-format output, and risk model are this repo's own. Release pipeline modeled on [`pavp/wavefront`](https://github.com/pavp/wavefront). Methodological credit: Bill Wake (INVEST, 2003), Mike Cohn (*User Stories Applied*, 2004), Dan North (BDD / Given-When-Then), Richard Lawrence & Peter Green (*Humanizing Work* splitting patterns).
+
+## What it is
+
+A **skills pack for Claude Code**, not a runtime. No LLM inside. Skills are Markdown files that Claude Code reads as instructions. The npm package is a thin installer that copies them to `~/.claude/skills/storywright/`.
+
+## Install
+
+```bash
+npm install -g @pavp/storywright
+storywright install
+```
+
+Restart Claude Code so the skills are picked up.
+
+Alternatives:
+
+- **Git clone + symlink** for contributors:
+  ```bash
+  git clone git@github.com:pavp/storywright.git
+  ln -s "$(pwd)/storywright/skills" ~/.claude/skills/storywright
+  ```
+- **ZIP upload to claude.ai**:
+  ```bash
+  storywright zip story-generate
+  # → dist/story-generate.zip — upload via Claude.ai UI
+  ```
+
+## Use
+
+In Claude Code:
+
+```
+generate a user story: Permitir login con Google
+```
+
+```
+refine this story:
+<paste a half-baked story>
+```
+
+```
+generate stories from this Figma: https://www.figma.com/file/…
+```
+
+```
+this story is too big, split it:
+<paste a story that visibly mixes flows>
+```
+
+Outputs always include both `story.jira-wiki.md` (Jira wiki markup) and `story.standard.md` (CommonMark).
+
+## Skills
+
+### Top-level
+| Skill | When to use |
+|---|---|
+| `story-generate` | Ambiguous prompt, screenshot, or fresh story request |
+| `story-refine` | Existing story that's incomplete or weakly specified |
+| `story-split` | Story that fails INVEST on I / E / S — too big |
+| `story-from-figma` | Figma file or frame URL → one or more stories |
+
+### Components (composed by the top-level skills)
+- `clarification-questions` — minimum critical questions
+- `acceptance-criteria` — Given/When/Then ACs
+- `invest-checklist` — INVEST self-check with verdict
+- `definition-of-done` — DoD checkbox block
+- `business-rules` — policy invariants
+- `edge-cases` — boundary/network/concurrency/permission/state
+- `analytics-events` — funnel events with payload taxonomy
+- `risks-and-dependencies` — risks + blocking deps
+- `jira-wiki-formatter` — dual-format renderer
+
+## Multimodal
+
+| Input | Runtime | Notes |
+|---|---|---|
+| Text | Native | Always available |
+| Images (PNG/JPG) | Claude vision | Drop file into chat |
+| Figma links | MCP Figma server | See `skills/story-from-figma/mcp-figma-notes.md` |
+
+## CLI
+
+```bash
+storywright install            # copy skills to ~/.claude/skills/storywright/
+storywright list               # show available + installed skills
+storywright validate           # lint skill files (frontmatter + structure)
+storywright zip <skill-name>   # build a ZIP for Claude.ai upload
+storywright uninstall          # remove from ~/.claude/skills/
+```
+
+## Multi-provider stance
+
+Skills are written in **format-neutral Markdown** with optional `<claude-specific>` XML blocks. Non-Claude LLMs ignore the XML; Claude reads it. No adapters shipped — downstream concern.
+
+## Releases
+
+`semantic-release` + Conventional Commits + GitHub Actions + npm Trusted Publishing (OIDC). Push to `main` → bump → publish. Single `latest` channel for v1.
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+MIT

package/bin/storywright.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { spawn } from "node:child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const scriptsDir = resolve(__dirname, "..", "scripts");
+
+const [, , cmd, ...rest] = process.argv;
+
+const COMMANDS = {
+  install: "install-skills.mjs",
+  uninstall: "uninstall-skills.mjs",
+  list: "list-skills.mjs",
+  zip: "zip-skill.mjs",
+  validate: "validate-skills.mjs",
+};
+
+function usage(exit = 0) {
+  console.log(`storywright — PM skills for Claude Code
+
+Usage:
+  storywright install              Copy skills to ~/.claude/skills/storywright/
+  storywright uninstall            Remove skills from ~/.claude/skills/
+  storywright list                 Show available + installed skills
+  storywright zip <skill-name>     Build a ZIP for Claude.ai upload
+  storywright validate             Lint skill files (frontmatter + structure)
+
+Repo: https://github.com/pavp/storywright`);
+  process.exit(exit);
+}
+
+if (!cmd || cmd === "--help" || cmd === "-h") usage(0);
+if (!COMMANDS[cmd]) {
+  console.error(`Unknown command: ${cmd}\n`);
+  usage(1);
+}
+
+const script = resolve(scriptsDir, COMMANDS[cmd]);
+const child = spawn(process.execPath, [script, ...rest], { stdio: "inherit" });
+child.on("exit", (code) => process.exit(code ?? 1));

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@pavp/storywright",
+  "version": "1.0.0",
+  "description": "PM Skills pack for Claude Code — turn ambiguous inputs (prompts, screenshots, Figma links) into Jira-ready user stories.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "skills",
+    "product-management",
+    "user-stories",
+    "jira",
+    "agile",
+    "invest",
+    "ai-agent"
+  ],
+  "license": "MIT",
+  "author": "pavp <pedrovillarreal@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pavp/storywright.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pavp/storywright/issues"
+  },
+  "homepage": "https://github.com/pavp/storywright#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "storywright": "./bin/storywright.mjs"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "skills/",
+    ".claude-plugin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "validate": "node scripts/validate-skills.mjs",
+    "test": "node --test tests/*.test.mjs",
+    "postinstall": "node scripts/postinstall-hint.mjs",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.5.0",
+    "@commitlint/config-conventional": "^19.5.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.0",
+    "@semantic-release/npm": "^12.0.1",
+    "@semantic-release/release-notes-generator": "^14.0.1",
+    "conventional-changelog-conventionalcommits": "^8.0.0",
+    "husky": "^9.1.6",
+    "semantic-release": "^24.1.2"
+  }
+}

package/scripts/install-skills.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { homedir } from "node:os";
+import { cp, mkdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { SKILLS_DIR, pathExists } from "./lib/skills.mjs";
+
+const target = join(homedir(), ".claude", "skills", "storywright");
+
+async function main() {
+  if (await pathExists(target)) {
+    await rm(target, { recursive: true, force: true });
+    console.log(`• Removed existing ${target}`);
+  }
+  await mkdir(target, { recursive: true });
+  await cp(SKILLS_DIR, target, { recursive: true });
+  console.log(`✓ Installed skills to ${target}`);
+  console.log(`  Restart Claude Code (or reload) for skills to be picked up.`);
+}
+
+main().catch((err) => {
+  console.error("✗ Install failed:", err);
+  process.exit(1);
+});

package/scripts/lib/skills.mjs

@@ -0,0 +1,94 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const REPO_ROOT = join(__dirname, "..", "..");
+export const SKILLS_DIR = join(REPO_ROOT, "skills");
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
+
+export function parseFrontmatter(raw) {
+  const match = raw.match(FRONTMATTER_RE);
+  if (!match) return { frontmatter: null, body: raw };
+  const fmText = match[1];
+  const body = match[2];
+  const fm = parseSimpleYaml(fmText);
+  return { frontmatter: fm, body };
+}
+
+function parseSimpleYaml(text) {
+  const out = {};
+  let currentList = null;
+  let currentKey = null;
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.replace(/\s+$/, "");
+    if (!line.trim()) continue;
+    if (line.startsWith("  - ") || line.startsWith("- ")) {
+      const value = line.replace(/^\s*-\s*/, "").trim();
+      if (currentList) currentList.push(stripQuotes(value));
+      continue;
+    }
+    const m = line.match(/^([a-zA-Z0-9_]+):\s*(.*)$/);
+    if (!m) continue;
+    const key = m[1];
+    const rest = m[2];
+    if (rest === "" || rest == null) {
+      out[key] = [];
+      currentList = out[key];
+      currentKey = key;
+    } else {
+      out[key] = stripQuotes(rest);
+      currentList = null;
+      currentKey = key;
+    }
+  }
+  return out;
+}
+
+function stripQuotes(v) {
+  if (typeof v !== "string") return v;
+  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+    return v.slice(1, -1);
+  }
+  return v;
+}
+
+export async function findSkillFiles(root = SKILLS_DIR) {
+  const out = [];
+  async function walk(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const e of entries) {
+      const full = join(dir, e.name);
+      if (e.isDirectory()) {
+        await walk(full);
+      } else if (e.isFile() && e.name === "SKILL.md") {
+        out.push(full);
+      }
+    }
+  }
+  await walk(root);
+  return out;
+}
+
+export async function loadSkill(skillFilePath) {
+  const raw = await readFile(skillFilePath, "utf8");
+  const { frontmatter, body } = parseFrontmatter(raw);
+  return {
+    path: skillFilePath,
+    relPath: relative(REPO_ROOT, skillFilePath),
+    raw,
+    frontmatter: frontmatter ?? {},
+    body,
+  };
+}
+
+export async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/scripts/list-skills.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { homedir } from "node:os";
+import { join, relative } from "node:path";
+import { findSkillFiles, loadSkill, pathExists, SKILLS_DIR } from "./lib/skills.mjs";
+
+const installed = join(homedir(), ".claude", "skills", "storywright");
+
+async function main() {
+  const repoFiles = await findSkillFiles(SKILLS_DIR);
+  const installedExists = await pathExists(installed);
+
+  const tops = [];
+  const components = [];
+  for (const f of repoFiles) {
+    const skill = await loadSkill(f);
+    const entry = {
+      name: skill.frontmatter.name ?? "(unnamed)",
+      desc: skill.frontmatter.description ?? "",
+      path: relative(SKILLS_DIR, f),
+    };
+    if (skill.relPath.includes("_components/")) components.push(entry);
+    else tops.push(entry);
+  }
+
+  console.log(`Repo skills (${repoFiles.length} total)`);
+  console.log(`Installed at ~/.claude/skills/storywright/: ${installedExists ? "YES" : "NO"}\n`);
+
+  console.log(`Top-level skills (${tops.length}):`);
+  for (const s of tops) console.log(`  • ${s.name.padEnd(22)} — ${s.desc.slice(0, 80)}`);
+
+  console.log(`\nComponent skills (${components.length}):`);
+  for (const s of components) console.log(`  · ${s.name.padEnd(28)} — ${s.desc.slice(0, 70)}`);
+}
+
+main().catch((err) => {
+  console.error("✗ List failed:", err);
+  process.exit(1);
+});

package/scripts/postinstall-hint.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// Skip noise in CI and in nested installs.
+if (process.env.CI || process.env.npm_config_global !== "true") process.exit(0);
+
+console.log(`
+┌─────────────────────────────────────────────────────────────┐
+│  storywright installed                                      │
+│  Run:  storywright install                                  │
+│  to copy the skills into ~/.claude/skills/storywright/      │
+│  Then restart Claude Code to pick them up.                  │
+└─────────────────────────────────────────────────────────────┘
+`);

package/scripts/uninstall-skills.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { homedir } from "node:os";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { pathExists } from "./lib/skills.mjs";
+
+const target = join(homedir(), ".claude", "skills", "storywright");
+
+async function main() {
+  if (!(await pathExists(target))) {
+    console.log(`• Nothing to uninstall (${target} does not exist)`);
+    return;
+  }
+  await rm(target, { recursive: true, force: true });
+  console.log(`✓ Removed ${target}`);
+}
+
+main().catch((err) => {
+  console.error("✗ Uninstall failed:", err);
+  process.exit(1);
+});

package/scripts/validate-skills.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { join, dirname, basename } from "node:path";
+import { findSkillFiles, loadSkill, pathExists, SKILLS_DIR, REPO_ROOT } from "./lib/skills.mjs";
+
+const REQUIRED_FM = ["name", "description", "trigger", "intent", "version"];
+const REQUIRED_SECTIONS = ["## Purpose", "## Application"];
+const KEBAB_RE = /^[a-z][a-z0-9-]*$/;
+
+async function main() {
+  const files = await findSkillFiles();
+  if (files.length === 0) {
+    console.error("✗ No SKILL.md files found under skills/");
+    process.exit(1);
+  }
+
+  const errors = [];
+  const skillNames = new Set();
+  const componentPaths = new Set();
+
+  for (const f of files) {
+    const skill = await loadSkill(f);
+    const rel = skill.relPath;
+    const fm = skill.frontmatter;
+
+    for (const key of REQUIRED_FM) {
+      if (!fm[key] || (Array.isArray(fm[key]) && fm[key].length === 0)) {
+        errors.push(`${rel}: missing required frontmatter '${key}'`);
+      }
+    }
+
+    if (fm.name) {
+      if (!KEBAB_RE.test(fm.name)) {
+        errors.push(`${rel}: name '${fm.name}' must be kebab-case`);
+      }
+      if (fm.name.length > 64) {
+        errors.push(`${rel}: name length ${fm.name.length} > 64`);
+      }
+      if (skillNames.has(fm.name)) {
+        errors.push(`${rel}: duplicate skill name '${fm.name}'`);
+      } else {
+        skillNames.add(fm.name);
+      }
+    }
+
+    if (fm.description && fm.description.length > 200) {
+      errors.push(`${rel}: description length ${fm.description.length} > 200`);
+    }
+
+    for (const section of REQUIRED_SECTIONS) {
+      if (!skill.body.includes(section)) {
+        errors.push(`${rel}: missing required section '${section}'`);
+      }
+    }
+
+    if (rel.includes("skills/_components/")) {
+      componentPaths.add(`_components/${basename(dirname(f))}`);
+    }
+  }
+
+  for (const f of files) {
+    const skill = await loadSkill(f);
+    const composes = Array.isArray(skill.frontmatter.composes) ? skill.frontmatter.composes : [];
+    for (const dep of composes) {
+      if (!componentPaths.has(dep)) {
+        errors.push(`${skill.relPath}: composes references missing component '${dep}'`);
+      }
+    }
+  }
+
+  if (errors.length) {
+    console.error(`✗ Validation failed (${errors.length} error${errors.length === 1 ? "" : "s"}):\n`);
+    for (const e of errors) console.error(`  - ${e}`);
+    process.exit(1);
+  }
+
+  console.log(`✓ ${files.length} skills validated (${componentPaths.size} components, ${files.length - componentPaths.size} top-level)`);
+}
+
+main().catch((err) => {
+  console.error("✗ Validator crashed:", err);
+  process.exit(2);
+});

package/scripts/zip-skill.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { REPO_ROOT, SKILLS_DIR, pathExists } from "./lib/skills.mjs";
+
+const skillName = process.argv[2];
+if (!skillName) {
+  console.error("Usage: storywright zip <skill-name>");
+  console.error("Example: storywright zip story-generate");
+  process.exit(1);
+}
+
+async function main() {
+  const skillDir = join(SKILLS_DIR, skillName);
+  if (!(await pathExists(skillDir))) {
+    const compDir = join(SKILLS_DIR, "_components", skillName);
+    if (!(await pathExists(compDir))) {
+      console.error(`✗ Skill not found: ${skillName}`);
+      process.exit(1);
+    }
+  }
+  const sourceDir = (await pathExists(skillDir)) ? skillDir : join(SKILLS_DIR, "_components", skillName);
+  const outDir = join(REPO_ROOT, "dist");
+  if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+
+  const outFile = join(outDir, `${skillName}.zip`);
+  const result = spawnSync("zip", ["-r", outFile, "."], { cwd: sourceDir, stdio: "inherit" });
+
+  if (result.status !== 0) {
+    console.error(`✗ zip exited with status ${result.status}`);
+    process.exit(result.status ?? 1);
+  }
+  console.log(`✓ Wrote ${outFile}`);
+}
+
+main().catch((err) => {
+  console.error("✗ Zip failed:", err);
+  process.exit(1);
+});

package/skills/_components/acceptance-criteria/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: acceptance-criteria
+description: Write acceptance criteria for a user story in Given/When/Then style. Covers happy path, edge cases, and explicit non-goals. Returns only the AC block, never a full story.
+trigger: "internal use by story-* skills"
+intent: Component skill that produces a complete, testable acceptance-criteria block. Pure renderer — does not ask the user questions; relies on context already gathered upstream.
+version: 1.0.0
+inputs:
+  - story-context
+  - edge-cases-block
+outputs:
+  - acceptance-criteria-block
+---
+
+## Purpose
+
+Generate ACs that are **independently testable** and map directly to QA cases. Use Given/When/Then phrasing. Include negative cases. Pair with `[[edge-cases]]` so each edge case has at least one matching AC.
+
+## When to use
+
+Invoked by `story-generate` and `story-refine` after the body of the story is drafted.
+
+## Inputs & interpretation
+
+- **story-context** — title, user role, expected behavior summary
+- **edge-cases-block** — list of edge cases that must each be covered
+
+## Application (step-by-step)
+
+1. Start with the happy path: one AC for the primary success scenario.
+2. Add one AC per failure mode (auth failure, network error, validation error, permission denied).
+3. Add one AC per explicit edge case from `[[edge-cases]]`.
+4. Add one negative AC: "When [precondition not met], Then [no-op or error UX]."
+5. Each AC follows the pattern:
+   ```
+   **AC-N: <short title>**
+   - Given <precondition>
+   - When <action>
+   - Then <observable outcome>
+   - And <secondary observable outcome>  (optional)
+   ```
+6. Number ACs `AC-1`, `AC-2`, …. Stable numbering — never renumber when adding new ones in iterations.
+7. Emit only the AC block. Do NOT include explanations, headers above `## Criterios de Aceptación`, or surrounding prose.
+
+## Examples
+
+### Good
+
+```
+**AC-1: Successful Google login**
+- Given the user is on the login screen
+- When they tap "Continue with Google" and authorize a valid account
+- Then they are redirected to the dashboard within 3 seconds
+
+**AC-2: Account linking — same email exists with password**
+- Given an account with email user@x.com already exists with email/password
+- When the user logs in with Google using user@x.com
+- Then a "Link your account" confirmation screen is shown
+- And the user must enter their existing password to merge
+
+**AC-3: Cancellation in OAuth consent**
+- Given the user has tapped "Continue with Google"
+- When they cancel the Google consent screen
+- Then they are returned to the login screen with no error toast
+```
+
+### Bad
+
+```
+- It should work with Google
+- Handle errors properly
+- The user can log in
+```
+
+(no preconditions, no observables, untestable)
+
+## Splitting signal
+
+**Multiple When/Then pairs in one AC ⇒ story needs splitting.** Each `When` and each `Then` should be singular. If you find yourself writing AC-1 with three `When`s, that's not a story with rich ACs — it's three stories collapsed into one. Stop and hand off to `[[story-split]]`.
+
+Multiple `Given`s are fine — preconditions stack.
+
+## Common Pitfalls
+
+- Vague verbs (`work properly`, `handle correctly`, `improved performance`, `faster`). Use observable, measurable outcomes ("loads in <2s", "success toast shown").
+- Compound ACs (multiple `When`s or `Then`s). Split.
+- "So that" restates "I want to" — the value statement disappears. Dig until you find the real motivation ("so I don't lose work if the tab crashes" — not "so I can save").
+- Technical tasks disguised as stories ("As a developer, I want to refactor X"). If there's no observable user outcome, it's an eng task, not a story.
+- Forgetting non-goals — write at least one "Then it does NOT…" or mark as scope boundary.
+- Renumbering when adding ACs mid-iteration. Append, never renumber.
+
+## References
+
+- [[edge-cases]]
+- [[definition-of-done]]
+- [[business-rules]]
+
+<claude-specific>
+Use extended thinking to enumerate failure modes before drafting. Cache the Given/When/Then template.
+</claude-specific>