aip-user-stories Skill

1---2name: aip-user-stories3description: Generate verified recipe playbooks from AIPs with PR implementations (post mode), or speculative user stories from AIPs without implementations (pre mode). Use when the user provides an AIP URL or AIP content, optionally with PR URLs and file paths.4when_to_use: Trigger when the user mentions aip user stories, aip playbook, aip recipes, generate recipes from AIP, user stories for AIP, AIP guide, AIP how-to.5allowed-tools: Bash(gh pr view *) Bash(gh pr diff *) Read WebFetch(domain:cwiki.apache.org) WebFetch(domain:github.com)6argument-hint: <AIP-URL-or-pasted-content> [<PR-URL>...] [<file>...]7license: Apache-2.08---9 10<!-- SPDX-License-Identifier: Apache-2.011     https://www.apache.org/licenses/LICENSE-2.0 -->12 13# AIP-to-User-Stories Playbook14 15## Invocation16 17```18/aip-user-stories <AIP-URL-or-pasted-content> [<PR-URL>...] [<file>...]19```20 21If no arguments: print this usage synopsis and stop.22 23## Mode Detection24 25An argument starting with `https://cwiki.apache.org/confluence/` is the AIP URL. Arguments starting with `https://github.com/apache/airflow/pull/` are PR URLs. Other arguments are local file paths.26 27- **PR URLs present → post-implementation mode**: generates verified recipe playbooks from actual code.28- **No PR URLs → pre-implementation mode**: generates speculative user stories to help AIP authors validate design.29 30PR URLs signal post mode and serve as **discovery hints** — starting points for finding the implementation in the codebase. They are not an exhaustive list of all PRs for the feature, and the skill must explore beyond the supplied PRs to find the full implementation.31 32## AIP Number33 34Extract the AIP number from the URL path (e.g., `AIP-76` from a URL containing `/aip-76` or `/AIP-76`). If the number cannot be determined from the URL or pasted content, ask the user.35 36## Output Path37 38Write the final playbook to `.claude/aip-{number}.md` where `{number}` is the extracted AIP number. If the file already exists, ask the user before overwriting.39 40---41 42## Post-Implementation Mode43 44Source of truth: the **actual implementation** in the codebase and PRs — not the AIP specification. When the AIP proposes APIs that differ from what was implemented, the playbook follows the implementation.45 46### Phase 1 — Parse47 48Separate arguments into:49 50- **AIP source**: a URL to fetch, or pasted content already in the conversation.51- **PR URLs**: GitHub pull request URLs (one or more).52- **File paths**: local files (example Dags, source files, tests).53 54AIP content can come from a URL (fetched via WebFetch) or pasted directly by the user — both are equally valid input paths. If a URL fetch returns empty or garbled content, tell the user and ask them to paste the AIP content instead.55 56At least one PR URL is required in post mode. If none are provided but the mode was forced, ask for PR URLs.57 58### Phase 2 — Fetch & Discover59 60Retrieve initial sources:61 62- AIP content (from URL or already pasted).63- PR diffs and metadata via `gh pr view <number> --json title,body,files` and `gh pr diff <number>`.64- Local files specified as arguments.65 66Then use the PRs as **discovery seeds**: identify which modules, packages, and files the PRs touch, and explore outward from there:67 68- Read the touched files in their current state (not just the diff) to understand the full implementation.69- Follow imports, base classes, and related modules to find connected implementation code.70- Search for related example Dags, test files, and documentation that may not appear in the PR diffs.71- Grep for key class names, function names, and configuration keys from the AIP to find implementation spread across files the PRs didn't touch.72 73The PRs are a starting point, not a boundary. Code may have been implemented in other PRs, refactored since the PR merged, or spread across modules the PR didn't directly modify.74 75### Phase 3 — Analyze76 77Cross-reference AIP features against the **codebase** (not the PRs):78 79- Which AIP features are implemented (found in the current codebase)?80- Which AIP features are NOT implemented (proposed in AIP but absent from the codebase)?81- What patterns exist in tests and example Dags that demonstrate usage?82 83### Version Detection84 85Search PR diffs for `versionadded::` or `.. versionadded::` directives. If found, use that version. If not found, ask the user for the target Airflow version.86 87### Phase 4 — Propose88 89Present a numbered list of recipe candidates, grouped by concept:90 91```92**[Concept Group Name]**931. Recipe Title — one-sentence description of what the user accomplishes942. Recipe Title — one-sentence description95...96```97 98Each recipe maps to one distinct use case — a specific problem the user solves with this feature. If two API classes serve the same use case, combine them. If one class serves multiple use cases, split them.99 100For AIP features not found in the implementation, list them separately under **Not Yet Implemented** and ask the user: include with placeholder code, or skip?101 102Wait for user approval before generating.103 104### Phase 5 — Generate105 106For each approved recipe, produce content following the template in `references/playbook-template.md`.107 108**Code block tiers:**109 1101. **Verified** — the pattern exists in the codebase (source, example Dags, or tests). Use the code directly. No markers.1112. **Adapted** — combines verified components in a new way (e.g., using a verified mapper with a different asset). Clean code, with a brief note below the block: *"Adapted from [source file path]"*.1123. **Unverified** — no codebase evidence for this pattern. Use placeholders:113 114   ```python115   # TODO: Implement [description]116   # See: [reference or AIP section]117   ...118   ```119 120Verification sources: source code under `airflow-core/src/`, example Dags, and test files.121 122### Phase 6 — Assemble123 124Combine the overview and recipes into a playbook following the template structure. Write to `.claude/aip-{number}.md`.125 126If the user chose to skip unimplemented AIP features during the Propose phase, add a brief "Not Yet Implemented" section at the end listing them with one-line descriptions. Omit this section if all features were covered.127 128---129 130## Pre-Implementation Mode131 132Source of truth: the **AIP specification** itself. No implementation exists to verify against.133 134If file paths are provided, warn that they will be ignored (no implementation to reference).135 136### Phase 1 — Parse137 138Extract the AIP source: a URL to fetch, or pasted content. File path arguments are ignored with a warning.139 140AIP content can come from a URL or pasted directly — both are equally valid.141 142```143URL-based:  /aip-user-stories https://cwiki.apache.org/confluence/display/AIRFLOW/AIP-76144Paste-based: /aip-user-stories (then paste AIP content when prompted)145```146 147### Phase 2 — Fetch148 149Retrieve AIP content from URL or accept pasted content. If a URL fetch returns empty or garbled content, ask the user to paste the AIP content.150 151Ask the user for the target Airflow version (no PR to extract `versionadded` from).152 153### Phase 3 — Analyze154 155Extract from the AIP:156 157- Proposed features, APIs, and configuration options.158- Use cases described or implied.159- Code examples provided in the AIP itself.160 161No code verification — nothing is implemented yet.162 163### Phase 4 — Propose164 165Present a numbered list of user story candidates, grouped by concept:166 167```168**[Concept Group Name]**1691. Story Title — one-sentence description of the user goal1702. Story Title — one-sentence description171...172```173 174Wait for user approval before generating.175 176### Phase 5 — Generate177 178For each approved story, produce content following the template in `references/playbook-template.md` (pre-mode section).179 180ALL code blocks must be marked as speculative:181 182```python183# PROPOSED API — not yet implemented184```185 186Base speculative code on the AIP's own code examples and proposed API as closely as possible.187 188Each story must include **open design questions** that probe:189 190- **API ergonomics** — Is this easy to use correctly and hard to misuse?191- **Edge cases** — What happens with unusual inputs, empty partitions, or unexpected configurations?192- **Compatibility** — How does this interact with existing Airflow patterns (catchup, backfill, dynamic task mapping, sensors, XCom)?193- **Implementation feasibility** — What constraints or complexities has the AIP not addressed?194 195Questions must be specific to the story's use case. Generic questions ("what about error handling?") do not count.196 197### Phase 6 — Assemble198 199Combine the overview and user stories into a document following the template structure. Write to `.claude/aip-{number}.md`.200 201---202 203## Gotchas204 205- **Confluence pages often return partial or JavaScript-rendered content via WebFetch.** If the fetched AIP content looks incomplete (missing sections, garbled HTML), ask the user to paste the content. Don't generate from partial input.206- **PR diffs can show intermediate code that was later revised.** When multiple commits exist in a PR, prefer the final state of files (use `gh pr view` with `--json files` and read the current branch/merged code) over the raw diff, which may include since-reverted changes. More broadly, always prefer the current codebase state over PR diffs — PRs are discovery aids, not the source of truth.207- **AIP terminology drifts from implementation.** AIPs are written before (or during) implementation. Class names, parameter names, and module paths in the AIP frequently differ from what was actually merged. Always verify names against the codebase, not the AIP text.208- **Test files reveal use cases that examples miss.** Example Dags tend to show the happy path. Test files (especially parametrized tests) expose edge cases, error conditions, and alternative configurations that make better recipes.209- **An AIP feature listed as "implemented" in the AIP may not be in the PR.** AIPs track overall status, not per-PR scope. Cross-reference each feature against actual PR code, not the AIP's status section.210