.agents/skills/aip-user-stories/SKILL.md
/aip-user-stories <AIP-URL-or-pasted-content> [<PR-URL>...] [<file>...]
If no arguments: print this usage synopsis and stop.
An 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.
PR 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.
Extract 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.
Write 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.
Source 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.
Separate arguments into:
AIP 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.
At least one PR URL is required in post mode. If none are provided but the mode was forced, ask for PR URLs.
Retrieve initial sources:
gh pr view <number> --json title,body,files and gh pr diff <number>.Then use the PRs as discovery seeds: identify which modules, packages, and files the PRs touch, and explore outward from there:
The 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.
Cross-reference AIP features against the codebase (not the PRs):
Search PR diffs for versionadded:: or .. versionadded:: directives. If found, use that version. If not found, ask the user for the target Airflow version.
Present a numbered list of recipe candidates, grouped by concept:
**[Concept Group Name]**
1. Recipe Title — one-sentence description of what the user accomplishes
2. Recipe Title — one-sentence description
...
Each 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.
For AIP features not found in the implementation, list them separately under Not Yet Implemented and ask the user: include with placeholder code, or skip?
Wait for user approval before generating.
For each approved recipe, produce content following the template in references/playbook-template.md.
Code block tiers:
Verified — the pattern exists in the codebase (source, example Dags, or tests). Use the code directly. No markers.
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]".
Unverified — no codebase evidence for this pattern. Use placeholders:
# TODO: Implement [description]
# See: [reference or AIP section]
...
Verification sources: source code under airflow-core/src/, example Dags, and test files.
Combine the overview and recipes into a playbook following the template structure. Write to .claude/aip-{number}.md.
If 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.
Source of truth: the AIP specification itself. No implementation exists to verify against.
If file paths are provided, warn that they will be ignored (no implementation to reference).
Extract the AIP source: a URL to fetch, or pasted content. File path arguments are ignored with a warning.
AIP content can come from a URL or pasted directly — both are equally valid.
URL-based: /aip-user-stories https://cwiki.apache.org/confluence/display/AIRFLOW/AIP-76
Paste-based: /aip-user-stories (then paste AIP content when prompted)
Retrieve 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.
Ask the user for the target Airflow version (no PR to extract versionadded from).
Extract from the AIP:
No code verification — nothing is implemented yet.
Present a numbered list of user story candidates, grouped by concept:
**[Concept Group Name]**
1. Story Title — one-sentence description of the user goal
2. Story Title — one-sentence description
...
Wait for user approval before generating.
For each approved story, produce content following the template in references/playbook-template.md (pre-mode section).
ALL code blocks must be marked as speculative:
# PROPOSED API — not yet implemented
Base speculative code on the AIP's own code examples and proposed API as closely as possible.
Each story must include open design questions that probe:
Questions must be specific to the story's use case. Generic questions ("what about error handling?") do not count.
Combine the overview and user stories into a document following the template structure. Write to .claude/aip-{number}.md.
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.