@pavp/storywright 1.0.0

package/skills/_components/analytics-events/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: analytics-events
+description: Propose analytics/event tracking for a story. Names events, payloads, and trigger points. Returns only the analytics block, ready for ProductOps to map.
+trigger: "internal use by story-* skills"
+intent: Component skill that drafts a small, opinionated set of analytics events using a consistent naming convention.
+version: 1.0.0
+inputs:
+  - story-context
+  - acceptance-criteria
+outputs:
+  - analytics-events-block
+---
+
+## Purpose
+
+Stories without analytics are stories without feedback. Propose the minimum set of events to measure adoption, funnel, and failure rate of the new behavior.
+
+## When to use
+
+After acceptance criteria are drafted; events should align to observable AC outcomes.
+
+## Inputs & interpretation
+
+- **story-context** — feature surface, user role
+- **acceptance-criteria** — each happy-path AC suggests one funnel step
+
+## Application (step-by-step)
+
+1. Identify the funnel: entry → action → success / failure outcomes.
+2. For each step, define one event using `feature_action_state` snake_case naming:
+   - `login_google_started`
+   - `login_google_consent_granted`
+   - `login_google_completed`
+   - `login_google_failed`
+3. For each event, define payload fields. Always include:
+   - `user_id` (when known)
+   - `surface` (web | mobile-ios | mobile-android)
+   - `correlation_id` (links events of one attempt)
+   - `error_code` (only on failure events)
+4. Mark each event:
+   - `📊 product` — feeds dashboards / funnels
+   - `🔧 ops` — feeds error monitoring
+   - `💰 revenue` — feeds growth metrics
+5. Note retention/PII boundaries explicitly when sensitive (e.g., emails hashed).
+6. Emit under `### Analytics / Eventos`.
+
+Example block:
+
+```
+### Analytics / Eventos
+| Event | Trigger | Payload | Tag |
+|---|---|---|---|
+| `login_google_started` | tap "Continue with Google" | `surface`, `correlation_id` | 📊 |
+| `login_google_completed` | session created | `user_id`, `surface`, `correlation_id` | 📊 |
+| `login_google_failed` | error in callback | `surface`, `correlation_id`, `error_code` | 🔧 |
+| `account_link_prompted` | linking screen shown | `user_id`, `surface` | 📊 |
+
+> PII: email hashes only. No raw emails in event payload.
+```
+
+## Examples
+
+### Good
+
+See above — minimal funnel, clear taxonomy, PII note included.
+
+### Bad
+
+```
+- Track login button click.
+- Track error.
+```
+
+(no payload, no taxonomy, no PII boundary)
+
+## Common Pitfalls
+
+- Over-instrumenting (12 events per story). Aim for ≤6.
+- Inconsistent naming (`googleLogin`, `g_login`, `loginGoogle` in same story).
+- Forgetting `correlation_id` — without it you cannot join events into a funnel.
+- Putting raw PII in payloads.
+
+## References
+
+- [[acceptance-criteria]]
+- [[definition-of-done]]
+
+<claude-specific>
+Cache the 4 required payload fields and the 3 tag emojis.
+</claude-specific>

package/skills/_components/business-rules/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: business-rules
+description: Extract and articulate business rules a story must honor. Distinguish rules (always true) from acceptance criteria (testable on this story). Returns only the rules block.
+trigger: "internal use by story-* skills"
+intent: Component skill that surfaces invariants, policies, and constraints that bound a story without being acceptance criteria themselves.
+version: 1.0.0
+inputs:
+  - story-context
+  - domain-hints
+outputs:
+  - business-rules-block
+---
+
+## Purpose
+
+Business rules are **policy invariants** the story must respect. They survive across stories; they bound the design space.
+
+## When to use
+
+After the story body is drafted, before ACs are finalized — so ACs can reference relevant rules.
+
+## Inputs & interpretation
+
+- **story-context** — domain (auth, billing, content, etc.)
+- **domain-hints** — explicit references in the prompt to limits, eligibility, permissions
+
+## Application (step-by-step)
+
+1. Enumerate candidate rules across these categories:
+   - **Eligibility** (who can perform the action)
+   - **Limits** (rate, quota, size, duration)
+   - **Permissions / roles**
+   - **Data validity** (format, ranges, required combinations)
+   - **Compliance** (GDPR, PCI, accessibility legal floor)
+   - **Lifecycle** (creation, expiration, deletion rules)
+2. For each candidate, write as an imperative statement: `Only X can Y`, `Y must be Z`, `Y expires after N`.
+3. Drop rules already implied by Acceptance Criteria — rules state the *why* AC exist.
+4. Mark unresolved rules with `> ⚠️ Confirm:` and bubble them up to `[[clarification-questions]]`.
+5. Emit as numbered list under `### Reglas de Negocio` (or English equivalent based on input language).
+
+## Examples
+
+### Good
+
+```
+### Reglas de Negocio
+1. Solo usuarios con cuentas Google verificadas pueden usar el login social.
+2. El email del IdP debe coincidir con un dominio permitido si la cuenta es Workspace.
+3. La sesión expira tras 30 días de inactividad.
+4. Un usuario no puede tener simultáneamente login social y password sin haber pasado por flujo de account-linking.
+> ⚠️ Confirm: ¿Se permite descrear el vínculo Google una vez establecido?
+```
+
+### Bad
+
+```
+- Login should be secure.
+- Users should be happy.
+```
+
+(not invariants, not actionable)
+
+## Common Pitfalls
+
+- Conflating rules with ACs. AC = testable on this story. Rule = always true.
+- Stating implementation ("use OAuth 2.0 with PKCE"). That belongs in technical considerations.
+- Inventing rules. If you can't source the rule, mark it `⚠️ Confirm:`.
+
+## References
+
+- [[acceptance-criteria]]
+- [[clarification-questions]]
+- [[risks-and-dependencies]]
+
+<claude-specific>
+Cache the 6 category list. Use extended thinking when domain is high-stakes (auth, payments, PII).
+</claude-specific>

package/skills/_components/clarification-questions/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: clarification-questions
+description: Surface only the critical questions blocking a complete user story. Ask the minimum needed; never quiz the user. Used by every top-level story skill.
+trigger: "internal use by story-* skills"
+intent: Component skill that runs a gap analysis on an input and emits ordered, high-leverage clarifying questions. Asks zero questions when the input is already complete.
+version: 1.0.0
+inputs:
+  - text
+  - image
+  - figma-context
+outputs:
+  - clarifying-questions-block
+---
+
+## Purpose
+
+Turn vague inputs into a short, prioritized question list. The goal is **minimal friction**: ask only what blocks writing a usable story. Many prompts are answerable with reasonable assumptions — favor making the assumption (and marking it) over asking.
+
+## When to use
+
+Invoked by `story-generate`, `story-refine`, `story-split`, and `story-from-figma` after intake.
+
+## Inputs & interpretation
+
+- **text** — raw prompt, half-baked story, or paragraph
+- **image** — Claude vision interprets a screenshot/mockup; pass the inferred description
+- **figma-context** — frame names, navigation hints, components, states
+
+## Application (step-by-step)
+
+1. Run a gap check across these axes:
+   - **Who** (user/persona)
+   - **What outcome** (business value)
+   - **Trigger / entry point**
+   - **Success state**
+   - **Failure / error states**
+   - **Data inputs** (auth scope, identifiers, format)
+   - **Constraints** (platform, accessibility, locale, SLA)
+   - **Out-of-scope assumptions**
+2. For each axis, mark one of: ANSWERED · INFERRABLE · BLOCKING.
+3. Drop `ANSWERED`. For `INFERRABLE`, do NOT ask — mark assumption in the story output with `> ⚠️ Assumed:`.
+4. For `BLOCKING`, draft questions. Limit to **3 questions max per round**. Prefer multiple-choice or yes/no.
+5. Order by impact: scope > behavior > data > UX detail.
+6. Emit as a Markdown block titled `### Clarifying Questions` with numbered list.
+7. If no questions remain, emit nothing.
+
+## Examples
+
+### Good
+
+Input: *"Permitir login con Google"*
+
+```
+### Clarifying Questions
+1. **Scope of accounts** — debe aceptar cualquier cuenta Google, solo Workspace del dominio X, o ambos?
+2. **Account linking** — qué pasa si el email ya existe con login email/password? merge automático, error, o pantalla de claim?
+3. **Mobile vs web** — el flujo cubre solo web ahora, o también mobile en este ticket?
+```
+
+### Bad
+
+Asking 8 questions including UX color, button copy, and analytics naming. That's pollution — most are inferrable or trivially defaultable.
+
+## Common Pitfalls
+
+- Asking instead of inferring. If a sensible default exists, take it and mark `⚠️ Assumed`.
+- Stacking questions in one bullet. One ask per bullet.
+- Open-ended questions ("¿qué te parece…?"). Make them concrete and answerable in <1 sentence.
+- More than 3 questions per round. Iteration is fine; interrogation is not.
+
+## References
+
+- [[story-generate]]
+- [[story-refine]]
+- [[clarification-questions-output-format]] (in story-generate templates)
+
+<claude-specific>
+Use a structured-thinking pass to enumerate the 8 axes before deciding which are BLOCKING. Cache the axes list across invocations within the same session.
+</claude-specific>

package/skills/_components/definition-of-done/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: definition-of-done
+description: Produce a Definition of Done block for a user story. Covers code, tests, analytics, docs, accessibility, and release gates. Returns only the DoD block.
+trigger: "internal use by story-* skills"
+intent: Component skill that emits a baseline DoD aligned to common product/eng standards. Customizable via project-level overrides documented in the story.
+version: 1.0.0
+inputs:
+  - story-context
+  - technical-considerations
+outputs:
+  - definition-of-done-block
+---
+
+## Purpose
+
+A Definition of Done is the contract for "shippable". It must be **checkable, observable, and binary** — never aspirational.
+
+## When to use
+
+Invoked by `story-generate` after acceptance criteria and technical considerations are drafted.
+
+## Inputs & interpretation
+
+- **story-context** — what's being built
+- **technical-considerations** — surface (frontend, backend, mobile) drives which DoD lines apply
+
+## Application (step-by-step)
+
+1. Start from the baseline list below.
+2. Drop lines that don't apply (e.g., no analytics if the story is purely internal).
+3. Add story-specific lines from technical considerations (e.g., "Database migration runs cleanly on staging").
+4. Use checkbox markdown (`- [ ]`) so reviewers can tick during review.
+
+### Baseline DoD
+
+```
+### Definition of Done
+- [ ] Code merged to main behind feature flag (if applicable)
+- [ ] All acceptance criteria pass in QA environment
+- [ ] Unit tests added/updated; coverage not decreased
+- [ ] Integration / E2E test added for the happy path and at least one failure mode
+- [ ] Accessibility: keyboard navigable, screen-reader labels, color contrast ≥ WCAG AA
+- [ ] Analytics events implemented and verified in dashboard
+- [ ] Error states surfaced to user with actionable copy
+- [ ] Translations added for all user-facing strings (per project locale list)
+- [ ] Documentation updated (README / runbook / API docs as relevant)
+- [ ] Reviewed by ≥1 engineer; PM signoff after acceptance walkthrough
+- [ ] No regressions in critical-path E2E suite
+```
+
+5. Emit only the block. Do NOT add prose around it.
+
+## Examples
+
+### Good
+
+A backend-only story drops the WCAG line, keeps unit/integration tests, adds a migration line.
+
+### Bad
+
+`- [ ] Quality is good` — not checkable.
+
+## Common Pitfalls
+
+- Treating DoD as aspirational. Every box must be objectively tickable.
+- Copy-pasting a generic DoD onto every story. Trim what doesn't apply.
+- Confusing DoD with AC. AC = "what does this story do?". DoD = "what does shippable mean for any story in this team?".
+
+## References
+
+- [[acceptance-criteria]]
+- [[analytics-events]]
+
+<claude-specific>
+Cache the baseline DoD block across calls in the session.
+</claude-specific>

package/skills/_components/edge-cases/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: edge-cases
+description: Enumerate edge cases for a story. Covers boundary, concurrency, network, data, permission, and UX-state failures. Returns only the edge-cases block.
+trigger: "internal use by story-* skills"
+intent: Component skill that systematically generates edge cases across known failure axes so acceptance criteria can cover them.
+version: 1.0.0
+inputs:
+  - story-context
+outputs:
+  - edge-cases-block
+---
+
+## Purpose
+
+Edge cases are how engineers find latent risk. Generate them **before** acceptance criteria so each one pairs to an AC.
+
+## When to use
+
+Invoked by `story-generate` after the story body and business rules are drafted; output feeds `[[acceptance-criteria]]`.
+
+## Inputs & interpretation
+
+- **story-context** — surface, primary flow, data shape
+
+## Application (step-by-step)
+
+Walk these axes and pick the ones that apply:
+
+1. **Boundary** — empty input, single item, max length, max collection size
+2. **Network** — offline, timeout, slow connection, intermittent
+3. **Concurrency** — two devices simultaneously, race conditions, stale state
+4. **Permission** — unauthenticated, expired session, insufficient role, revoked access
+5. **Data integrity** — duplicate, conflicting, corrupted, partial
+6. **State** — already in target state, transition from unexpected source state
+7. **External** — third-party down, rate limit hit, response shape change
+8. **UX** — back/forward navigation mid-flow, deep-link entry, modal interrupt, accessibility tooling
+
+For each applicable axis, write 1–2 concrete cases. Keep each ≤1 sentence.
+
+Emit under `### Edge Cases`:
+
+```
+### Edge Cases
+- **Network — timeout during OAuth callback**: user sees a retry prompt; no orphan session created.
+- **Concurrency — same Google account in two tabs**: second tab inherits the same session.
+- **Permission — Workspace domain not allowed**: error toast with admin contact.
+- **State — already logged in with email/password**: route through account-linking flow.
+- **UX — back button during consent**: returns to login screen, no partial state.
+```
+
+## Examples
+
+### Good
+
+See above — concrete, observable, mappable to ACs.
+
+### Bad
+
+`- Lots of weird stuff might happen.` (no axis, no observable outcome)
+
+## Common Pitfalls
+
+- Listing "what if user does something dumb" — not actionable. Tie to an axis.
+- Over-enumerating. 5–10 edge cases is healthier than 30. Pick the high-impact ones.
+- Forgetting non-functional edges (offline, slow network).
+
+## References
+
+- [[acceptance-criteria]]
+- [[risks-and-dependencies]]
+
+<claude-specific>
+Cache the 8 axes. Use extended thinking when surface is novel.
+</claude-specific>

package/skills/_components/invest-checklist/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: invest-checklist
+description: Run an INVEST self-check on a drafted user story. Flag failures with concrete diagnosis. Used by story-generate after drafting and by story-split as the split trigger.
+trigger: "internal use by story-* skills"
+intent: Component skill that scores a story across the six INVEST dimensions and emits a pass/fail diagnosis with reasons. Never auto-splits.
+version: 1.0.0
+inputs:
+  - story-draft
+outputs:
+  - invest-report-block
+---
+
+## Purpose
+
+INVEST is the gate that separates ready stories from epics in disguise. Score honestly. Failures here are signals, not opinions.
+
+## When to use
+
+- After `story-generate` drafts a story → run to confirm readiness.
+- At the start of `story-split` → use the failure reasons as the split rationale.
+
+## Inputs & interpretation
+
+- **story-draft** — full story content (title + sections)
+
+## Application (step-by-step)
+
+For each dimension, mark PASS / FAIL and write one sentence of evidence.
+
+1. **I — Independent**
+   PASS if the story can be delivered without waiting on another story.
+   FAIL if it explicitly depends on uncommitted work or requires a parallel change in another team's surface.
+
+2. **N — Negotiable**
+   PASS if scope can shift without breaking the story (the user/team retains flexibility on HOW).
+   FAIL if the story over-specifies implementation (specific endpoints, exact pixel values mandated, locked tech).
+
+3. **V — Valuable**
+   PASS if the value statement names a user or business outcome.
+   FAIL if the only beneficiary is "the system" or it's purely technical with no surfaced value.
+
+4. **E — Estimable**
+   PASS if the team can confidently size it within their tolerance band (e.g., ≤8 SP).
+   FAIL if unknowns dominate (spike-shaped) or the surface is too broad.
+
+5. **S — Small**
+   PASS if it fits one sprint and one developer-week is plausible.
+   FAIL if it visibly mixes ≥2 distinct flows or touches ≥3 unrelated surfaces.
+
+6. **T — Testable**
+   PASS if every AC has an observable outcome.
+   FAIL if ACs hand-wave behavior or rely on subjective judgment.
+
+7. Emit the report block:
+   ```
+   ### INVEST Check
+   - I — PASS · <evidence>
+   - N — PASS · <evidence>
+   - V — FAIL · <evidence>
+   - E — PASS · <evidence>
+   - S — FAIL · <evidence>
+   - T — PASS · <evidence>
+
+   **Verdict:** READY | NEEDS REFINEMENT | SPLIT RECOMMENDED
+   ```
+
+8. **Verdict logic:**
+   - All PASS → `READY`
+   - **V FAILS → `NOT A STORY`**. Hard stop. This is a tech task or infrastructure work, not a user story. Do not refine, do not split — reframe with user-visible value or combine with related user-facing work.
+   - **T FAILS → `NEEDS REFINEMENT`**. Fix ACs in place via `[[story-refine]]`. Do NOT split — splitting untestable input produces untestable children.
+   - **N FAILS → `NEEDS REFINEMENT`**. The story over-prescribes implementation; rewrite to focus on outcome, not solution.
+   - **E FAILS due to unknowns → `RUN A SPIKE`**. Recommend a 1–2 day time-boxed investigation before splitting.
+   - **I, E (size-driven), or S FAIL → `SPLIT RECOMMENDED`**. Hand off to `[[story-split]]`.
+
+9. Never auto-split here. Output is advisory only.
+
+## Examples
+
+### Good
+
+```
+### INVEST Check
+- I — PASS · No upstream dependencies; auth provider is already integrated.
+- N — PASS · Implementation is open beyond "use existing GoogleSignIn SDK".
+- V — PASS · Reduces signup friction for users without an account.
+- E — FAIL · Account-linking edge case requires backend schema research (spike-shaped).
+- S — FAIL · Covers web AND mobile AND account-linking in one story.
+- T — PASS · Each AC has observable outcomes.
+
+**Verdict:** SPLIT RECOMMENDED
+```
+
+### Bad
+
+`Verdict: READY` with no per-dimension evidence — review can't audit it.
+
+## Common Pitfalls
+
+- Calling a story `Small` because it's described in few sentences. Size is about scope, not word count.
+- Calling a story `Testable` when ACs only exist for the happy path.
+- Lumping `Independent` and `Negotiable` into one check.
+
+## References
+
+- [[story-split]]
+- [[acceptance-criteria]]
+- [[definition-of-done]]
+
+<claude-specific>
+Use extended thinking. The dimensions interact (small often forces independent). Resolve all six before emitting verdict.
+</claude-specific>

package/skills/_components/jira-wiki-formatter/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: jira-wiki-formatter
+description: Render a story into both Jira wiki markup and standard CommonMark Markdown. Outputs two artifacts so the same story is copy-pasteable into Jira and into any MD-aware tool.
+trigger: "internal use by story-* skills"
+intent: Component skill that takes a structured story (all sections drafted) and produces two output files following the templates in story-generate/templates.
+version: 1.0.0
+inputs:
+  - structured-story
+outputs:
+  - story.jira-wiki.md
+  - story.standard.md
+---
+
+## Purpose
+
+Stories need to live in Jira AND in any other markdown surface (Notion, Linear, GitHub Issues, internal wikis). Generate both representations from the same source.
+
+## When to use
+
+Final step in `story-generate` and `story-refine`. Always last.
+
+## Inputs & interpretation
+
+- **structured-story** — an object/dict with every section: title, description, user_story, contexto, objetivo, alcance, fuera_de_alcance, reglas_de_negocio, consideraciones_tecnicas, dependencias, riesgos, analytics, edge_cases, criterios_de_aceptacion, definition_of_done
+
+## Application (step-by-step)
+
+1. Render `story.jira-wiki.md` using Jira's wiki markup:
+   - Headings: `h1. `, `h2. `, `h3. `
+   - Bold: `*text*`
+   - Italic: `_text_`
+   - Code: `{{code}}` inline, `{code}…{code}` block
+   - Lists: `* item`, `# item` (numbered)
+   - Tables: `||header||header||` then `|cell|cell|`
+   - Panels for callouts: `{panel:title=⚠️ Assumed}…{panel}`
+2. Render `story.standard.md` using CommonMark:
+   - Headings: `##`, `###`
+   - Bold: `**text**`
+   - Italic: `*text*`
+   - Code: `` `inline` ``, ```` ``` ```` blocks
+   - Lists: `- item`, `1. item`
+   - Tables: standard pipe tables
+   - Callouts: `> ⚠️ **Assumed:** …`
+3. Section model = **core + optional**.
+
+   **Core (always emit, in this order):**
+   1. Title
+   2. Summary
+   3. User Story (As a / I want to / so that)
+   4. Acceptance Criteria
+   5. Definition of Done
+
+   **Optional (emit only if non-empty, in this order, after a separator):**
+   6. Contexto
+   7. Business Goal
+   8. Scope
+   9. Out of Scope
+   10. Business Rules
+   11. Technical Considerations
+   12. Dependencies
+   13. Risks
+   14. Analytics
+   15. Edge Cases
+
+4. **Drop any section with no real content.** An empty heading is noise. A story with only the 5 core sections is a valid output.
+5. Emit both as fenced code blocks in the chat (so user can copy), and offer to save to disk when running from CLI.
+
+## Examples
+
+### Good — Jira wiki
+
+```
+h2. Login con Google
+
+Permitir a usuarios autenticarse mediante OAuth con Google.
+
+h3. User Story
+*As a* visitante nuevo
+*I want* iniciar sesión con mi cuenta de Google
+*So that* puedo evitar crear una nueva contraseña.
+
+h3. Criterios de Aceptación
+*AC-1: Login exitoso*
+* Given el usuario está en la pantalla de login
+* When toca "Continuar con Google" y autoriza una cuenta válida
+* Then es redirigido al dashboard en <3s
+
+h3. Definition of Done
+* (/) Code merged behind feature flag
+* (/) ACs pass in QA
+```
+
+### Good — CommonMark
+
+```
+## Login con Google
+
+Permitir a usuarios autenticarse mediante OAuth con Google.
+
+### User Story
+**As a** visitante nuevo
+**I want** iniciar sesión con mi cuenta de Google
+**So that** puedo evitar crear una nueva contraseña.
+
+### Criterios de Aceptación
+**AC-1: Login exitoso**
+- Given el usuario está en la pantalla de login
+- When toca "Continuar con Google" y autoriza una cuenta válida
+- Then es redirigido al dashboard en <3s
+
+### Definition of Done
+- [ ] Code merged behind feature flag
+- [ ] ACs pass in QA
+```
+
+## Common Pitfalls
+
+- Mixing Jira and CommonMark in the same file. Pick one per file.
+- Forgetting that Jira's `{code}` block doesn't support all languages — fall back to `{noformat}` for plain text.
+- Emoji in Jira: works in cloud, often mangled in older self-hosted. Keep emojis to non-critical decoration.
+- Empty headings. Drop.
+
+## References
+
+- [[story-generate]] (templates live under `story-generate/templates/`)
+
+<claude-specific>
+Cache both syntax tables (Jira wiki and CommonMark) — they're stable.
+</claude-specific>