autodoc-agent-kit 1.0.0

package/src/modules/product/skills/user-story/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: user-story
+description: Create user stories with Mike Cohn format and Gherkin acceptance criteria. Use when turning user needs into development-ready work with clear outcomes and testable conditions.
+intent: >-
+  Create clear, concise user stories that combine Mike Cohn's user story format with Gherkin-style acceptance criteria. Use this to translate user needs into actionable development work that focuses on outcomes, ensures shared understanding between product and engineering, and provides testable success criteria.
+type: component
+theme: pm-artifacts
+best_for:
+  - "Writing user stories with proper acceptance criteria"
+  - "Converting requirements into development-ready stories"
+  - "Establishing story quality standards across your team"
+scenarios:
+  - "I need to write a user story for a new notification system in our B2B SaaS app"
+  - "Convert this PRD requirement into a properly formatted user story with Gherkin acceptance criteria"
+estimated_time: "5-10 min"
+---
+
+
+## Purpose
+Create clear, concise user stories that combine Mike Cohn's user story format with Gherkin-style acceptance criteria. Use this to translate user needs into actionable development work that focuses on outcomes, ensures shared understanding between product and engineering, and provides testable success criteria.
+
+This is not a feature spec—it's a conversation starter that captures *who* benefits, *what* they're trying to do, *why* it matters, and *how* you'll know it works.
+
+## Key Concepts
+
+### The Mike Cohn + Gherkin Format
+A user story combines:
+
+**Use Case (Mike Cohn format):**
+- **As a** [user persona/role]
+- **I want to** [action to achieve outcome]
+- **so that** [desired outcome]
+
+**Acceptance Criteria (Gherkin format):**
+- **Scenario:** [Brief description of the scenario]
+- **Given:** [Initial context or preconditions]
+- **and Given:** [Additional preconditions]
+- **When:** [Event that triggers the action]
+- **Then:** [Expected outcome]
+
+### Why This Structure Works
+- **User-centric:** Forces focus on who benefits and why
+- **Outcome-focused:** "So that" emphasizes the value delivered, not just the action
+- **Testable:** Gherkin acceptance criteria are concrete and verifiable
+- **Conversational:** Story is the opening for discussion, not the final spec
+- **Shared language:** Product, engineering, and QA all understand the format
+
+### Anti-Patterns (What This Is NOT)
+- **Not a task:** "As a developer, I want to refactor the database" (this is a tech task, not user value)
+- **Not a feature list:** "I want dashboards, reports, and analytics" (this is too big—needs splitting)
+- **Not vague:** "I want a better experience" (unmeasurable, no clear outcome)
+- **Not a contract:** Stories are placeholders for conversation, not locked-in specs
+
+### When to Use This
+- Translating user needs into development work
+- Backlog grooming and sprint planning
+- Communicating value to engineering and design
+- Ensuring testable acceptance criteria exist before development
+
+### When NOT to Use This
+- For pure technical debt or refactoring (use engineering tasks instead)
+- When stories are too large (split first—see `skills/user-story-splitting/SKILL.md`)
+- Before understanding the user problem (write a problem statement first)
+
+---
+
+## Application
+
+### Step 1: Gather Context
+Before writing a story, ensure you have:
+- **User persona:** Who is this for? (reference `skills/proto-persona/SKILL.md`)
+- **Problem understanding:** What need does this address? (reference `skills/problem-statement/SKILL.md`)
+- **Desired outcome:** What does success look like?
+- **Constraints:** Technical, time, or scope limitations
+
+**If missing context:** Run discovery interviews or problem validation work first.
+
+---
+
+### Optional Helper Script (Template Generator)
+
+If you want a consistent Markdown stub, you can generate one from CLI inputs. This script is deterministic and does not fetch data or write files.
+
+```bash
+python3 scripts/user-story-template.py --persona \"trial user\" --action \"log in with Google\" --outcome \"access the app without creating a new password\"
+```
+
+---
+
+### Step 2: Write the Use Case
+
+Use `template.md` for the full fill-in structure.
+
+Fill in the template:
+
+```markdown
+### User Story [ID]:
+
+- **Summary:** [Brief, memorable title focused on value to the user]
+
+#### Use Case:
+- **As a** [user name if available, otherwise persona, otherwise role]
+- **I want to** [action user takes to get to outcome]
+- **so that** [desired outcome]
+```
+
+**Quality checks:**
+- **"As a" specificity:** Is this a specific persona (e.g., "trial user") or generic ("user")?
+- **"I want to" clarity:** Is this an action the user takes, or a feature you're building?
+- **"So that" outcome:** Does this explain the user's motivation? Or is it just restating the action?
+
+**Common mistakes:**
+- ❌ "As a user, I want a login button, so that I can log in" (restating the action)
+- ✅ "As a trial user, I want to log in with Google, so that I can access the app without creating a new password"
+
+---
+
+### Step 3: Write the Acceptance Criteria
+
+Fill in the template:
+
+```markdown
+#### Acceptance Criteria:
+
+- **Scenario:** [Brief, human-readable scenario describing value]
+- **Given:** [Initial context or precondition]
+- **and Given:** [Additional context or preconditions]
+- **and Given:** [Additional context as needed]
+- **and Given:** [UI-focused context ensuring 'When' can happen]
+- **and Given:** [Outcomes-focused context ensuring 'Then' is delivered]
+- **When:** [Event that triggers the action—aligns with 'I want to']
+- **Then:** [Expected outcome—aligns with 'so that']
+```
+
+**Quality checks:**
+- **Multiple Givens are okay:** Preconditions stack up (e.g., "Given I'm logged in" + "Given I have items in my cart")
+- **Only one When:** If you need multiple "When" statements, you likely have multiple stories—split them
+- **Only one Then:** If you need multiple "Then" statements, you likely have multiple stories—split them
+- **Alignment:** Does "When" match "I want to"? Does "Then" match "so that"?
+
+**Red flags:**
+- **Multiple Whens/Thens:** Sign of scope creep—split the story (reference `skills/user-story-splitting/SKILL.md`)
+- **Vague Thens:** "Then I see improved performance" (unmeasurable—make it specific)
+
+---
+
+### Step 4: Add a Summary
+
+Write a short, memorable summary that captures the story's value:
+
+```markdown
+- **Summary:** [Brief, human-readable title]
+```
+
+**Examples:**
+- ✅ "Enable Google login for trial users to reduce signup friction"
+- ✅ "Bulk delete items to save time for power users"
+- ❌ "Add delete button" (feature-centric, not value-centric)
+
+---
+
+### Step 5: Validate and Refine
+
+- **Read aloud to the team:** Does everyone understand who, what, why?
+- **Test acceptance criteria:** Can QA write test cases from this?
+- **Check for splitting:** If the story feels too big, use `skills/user-story-splitting/SKILL.md`
+- **Ensure testability:** Can you prove "Then" happened?
+
+---
+
+## Examples
+
+See `examples/sample.md` for full examples (good, bad, and split-needed stories).
+
+Mini example excerpt:
+
+```markdown
+### User Story 042:
+
+- **Summary:** Enable Google login for trial users to reduce signup friction
+
+#### Use Case:
+- **As a** trial user visiting the app for the first time
+- **I want to** log in using my Google account
+- **so that** I can access the app without creating and remembering a new password
+
+#### Acceptance Criteria:
+- **Scenario:** First-time trial user logs in via Google OAuth
+- **Given:** I am on the login page
+- **and Given:** I have a login account
+- **When:** I click the "Sign in with Google" button and authorize the app
+- **Then:** I am logged into the app and redirected to the onboarding flow
+```
+
+---
+
+## Common Pitfalls
+
+### Pitfall 1: Technical Tasks Disguised as User Stories
+**Symptom:** "As a developer, I want to refactor the API, so that the code is cleaner"
+
+**Consequence:** This is an engineering task, not a user story. No user value is delivered.
+
+**Fix:** If there's no user outcome, it's not a user story—use an engineering task or tech debt ticket instead.
+
+---
+
+### Pitfall 2: "As a User" (Too Generic)
+**Symptom:** Every story starts with "As a user"
+
+**Consequence:** No persona clarity. Different users have different needs.
+
+**Fix:** Use specific personas: "As a trial user," "As a paid subscriber," "As an admin," etc. (reference `skills/proto-persona/SKILL.md`)
+
+---
+
+### Pitfall 3: "So That" Restates "I Want To"
+**Symptom:** "I want to click the save button, so that I can save my work"
+
+**Consequence:** No insight into *why* the user cares. Just restating the action.
+
+**Fix:** Dig into the motivation: "so that I don't lose my progress if the page crashes" (real outcome).
+
+---
+
+### Pitfall 4: Multiple When/Then Statements
+**Symptom:** Acceptance criteria with 5 "When" statements and 5 "Then" statements
+
+**Consequence:** Story is too big. Likely multiple features bundled together.
+
+**Fix:** Split the story using `skills/user-story-splitting/SKILL.md`. Each When/Then pair should be its own story (or at least evaluated for splitting).
+
+---
+
+### Pitfall 5: Untestable Acceptance Criteria
+**Symptom:** "Then the user has a better experience" or "Then it's faster"
+
+**Consequence:** QA can't verify success. Ambiguous definition of "done."
+
+**Fix:** Make it measurable: "Then the page loads in under 2 seconds" or "Then the user sees a success confirmation message."
+
+---
+
+## References
+
+### Related Skills
+- `skills/user-story-splitting/SKILL.md` — How to break large stories into smaller ones
+- `skills/proto-persona/SKILL.md` — Defines the "As a [persona]" section
+- `skills/problem-statement/SKILL.md` — Stories should address validated problems
+- `skills/epic-hypothesis/SKILL.md` — Epics decompose into user stories
+
+### Optional Helpers
+- `skills/user-story/scripts/user-story-template.py` — Deterministic Markdown stub generator (no network access)
+
+### External Frameworks
+- Mike Cohn, *User Stories Applied* (2004) — Origin of the "As a / I want / so that" format
+- Gherkin (Cucumber) — "Given/When/Then" acceptance criteria format
+- INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable)
+
+### Dean's Work
+- [Link to relevant Dean Peters' Substack articles if applicable]
+
+### Provenance
+- Adapted from `prompts/user-story-prompt-template.md` in the `https://github.com/deanpeters/product-manager-prompts` repo.
+
+---
+
+**Skill type:** Component
+**Suggested filename:** `user-story.md`
+**Suggested placement:** `/skills/components/`
+**Dependencies:** References `skills/proto-persona/SKILL.md`, `skills/problem-statement/SKILL.md`
+**Used by:** `skills/user-story-splitting/SKILL.md`, `skills/epic-hypothesis/SKILL.md`

package/src/modules/product/skills/user-story/examples/sample.md

@@ -0,0 +1,110 @@
+# User Story Examples
+
+## Example 1: Good User Story
+
+```markdown
+### User Story 042:
+
+- **Summary:** Enable Google login for trial users to reduce signup friction
+
+#### Use Case:
+- **As a** trial user visiting the app for the first time
+- **I want to** log in using my Google account
+- **so that** I can access the app without creating and remembering a new password
+
+#### Acceptance Criteria:
+
+- **Scenario:** First-time trial user logs in via Google OAuth
+- **Given:** I am on the login page
+- **and Given:** I have a Google account
+- **and Given:** The "Sign in with Google" button is visible
+- **When:** I click the "Sign in with Google" button and authorize the app
+- **Then:** I am logged into the app and redirected to the onboarding flow
+```
+
+**Why this works:**
+- Persona is specific ("trial user visiting for the first time")
+- Action is clear ("log in using my Google account")
+- Outcome explains motivation ("without creating a new password")
+- Acceptance criteria are testable (QA can verify each step)
+- Only one When, one Then (appropriately scoped)
+
+---
+
+## Example 2: Bad User Story (Too Vague)
+
+```markdown
+### User Story 999:
+
+- **Summary:** Improve login experience
+
+#### Use Case:
+- **As a** user
+- **I want to** better login
+- **so that** I can use the app
+
+#### Acceptance Criteria:
+
+- **Scenario:** User logs in
+- **Given:** I want to log in
+- **and Given:** I have an active account
+- **When:** I log in
+- **Then:** It works better
+```
+
+**Why this fails:**
+- "User" is too generic (trial user? returning user? admin?)
+- "Better login" is not an action (what specifically?)
+- "Use the app" is not a specific outcome (everyone wants to use the app)
+- Acceptance criteria are untestable ("works better" = unmeasurable)
+
+**How to fix it:**
+- Narrow the persona: "trial user," "returning user without password manager," etc.
+- Define the action: "log in using Google," "reset my password via email," etc.
+- Specify the outcome: "without remembering a new password," "in under 30 seconds," etc.
+- Make acceptance criteria falsifiable: "Then I am redirected to the dashboard within 2 seconds"
+
+---
+
+## Example 3: Story That Needs Splitting
+
+```markdown
+### User Story 100:
+
+- **Summary:** Manage shopping cart
+
+#### Use Case:
+- **As a** shopper
+- **I want to** add items, remove items, update quantities, apply coupons, and checkout
+- **so that** I can complete my purchase
+
+#### Acceptance Criteria:
+
+- **Scenario:** Shopping cart management
+- **Given:** I have items in my cart
+- **When:** I add an item
+- **Then:** It appears in the cart
+- **When:** I remove an item
+- **Then:** It disappears from the cart
+- **When:** I update quantity
+- **Then:** The quantity changes
+- **When:** I apply a coupon
+- **Then:** The discount is applied
+- **When:** I checkout
+- **Then:** I proceed to payment
+```
+
+**Why this needs splitting:**
+- Multiple "When" statements = multiple stories
+- Scope is too large for a single sprint
+- Different outcomes aren't related (adding items ≠ applying coupons)
+
+**How to split it:**
+Use `skills/user-story-splitting/SKILL.md` to break this into:
+1. "Add items to cart"
+2. "Remove items from cart"
+3. "Update item quantities"
+4. "Apply discount coupons"
+5. "Checkout and proceed to payment"
+
+Each becomes its own story with focused acceptance criteria.

package/src/modules/product/skills/user-story/scripts/user-story-template.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""Generate a user story Markdown snippet from CLI inputs.
+
+No network access. Prints to stdout.
+"""
+
+import argparse
+import sys
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Generate a user story with Gherkin-style acceptance criteria.",
+    )
+    parser.add_argument("--summary", help="Short summary/title for the story.")
+    parser.add_argument("--persona", help='Persona or role for "As a".')
+    parser.add_argument("--action", help='Action for "I want to".')
+    parser.add_argument("--outcome", help='Outcome for "so that".')
+    parser.add_argument("--scenario", help="Scenario description.")
+    parser.add_argument("--given", action="append", default=[], help="Given precondition (repeatable).")
+    parser.add_argument("--when", dest="when", help="When trigger.")
+    parser.add_argument("--then", dest="then", help="Then outcome.")
+    return parser.parse_args()
+
+
+def normalize(value: str, placeholder: str) -> str:
+    if value and value.strip():
+        return value.strip()
+    return placeholder
+
+
+def main() -> int:
+    args = parse_args()
+
+    summary = normalize(args.summary, "[Brief, memorable title focused on value]")
+    persona = normalize(args.persona, "[persona or role]")
+    action = normalize(args.action, "[action user takes to get to outcome]")
+    outcome = normalize(args.outcome, "[desired outcome]")
+    scenario = normalize(args.scenario, "[Brief, human-readable scenario describing value]")
+    whens = normalize(args.when, "[Event that triggers the action]")
+    thens = normalize(args.then, "[Expected outcome]")
+
+    givens = args.given or ["[Initial context or precondition]"]
+
+    print("### User Story [ID]:\n")
+    print(f"- **Summary:** {summary}\n")
+    print("#### Use Case:")
+    print(f"- **As a** {persona}")
+    print(f"- **I want to** {action}")
+    print(f"- **so that** {outcome}\n")
+    print("#### Acceptance Criteria:\n")
+    print(f"- **Scenario:** {scenario}")
+
+    for index, given in enumerate(givens):
+        label = "Given" if index == 0 else "and Given"
+        print(f"- **{label}:** {given}")
+
+    print(f"- **When:** {whens}")
+    print(f"- **Then:** {thens}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/modules/product/skills/user-story/template.md

@@ -0,0 +1,32 @@
+# User Story Template
+
+Use this template to write a single user story with Gherkin-style acceptance criteria.
+
+## Provenance
+Adapted from `prompts/user-story-prompt-template.md` in the `https://github.com/deanpeters/product-manager-prompts` repo.
+
+## Template
+```markdown
+### User Story [ID]:
+
+- **Summary:** [Brief, memorable title focused on user value]
+
+#### Use Case:
+- **As a** [user name if available, otherwise persona, otherwise role]
+- **I want to** [action the user takes to get to the outcome]
+- **so that** [desired outcome for the user]
+
+#### Acceptance Criteria:
+- **Scenario:** [Brief, human-readable scenario describing value]
+- **Given:** [Initial context or precondition]
+- **and Given:** [Additional context or preconditions]
+- **and Given:** [Additional context as needed]
+- **and Given:** [UI-focused context ensuring the When can happen]
+- **and Given:** [Outcomes-focused context ensuring the Then is delivered]
+- **When:** [Event that triggers the action]
+- **Then:** [Expected outcome aligned to "so that"]
+```
+
+## Notes
+- Use only one **When** and one **Then**. Multiple When/Then pairs usually mean the story should be split.
+- If you need multiple outcomes, split the story with `skills/user-story-splitting/SKILL.md`.