specrails-core 1.7.2 → 2.0.0

package/templates/skills/sr-product-backlog/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: sr-product-backlog
+description: "sr:product-backlog — View product-driven backlog from GitHub Issues and propose top 3 for implementation."
+license: MIT
+compatibility: "Requires GitHub CLI (gh)."
+metadata:
+  author: specrails
+  version: "1.0"
+---
+
+
+Display the product-driven backlog by reading issues/tickets from the configured backlog provider ({{BACKLOG_PROVIDER_NAME}}). These are feature ideas generated through VPC-based product discovery — evaluated against user personas. Use `/sr:update-product-driven-backlog` to generate new ideas.
+
+**Input:** $ARGUMENTS (optional: comma-separated areas to filter. If empty, show all.)
+
+---
+
+## Phase 0: Environment Pre-flight
+
+Verify the backlog provider is accessible:
+
+```bash
+{{BACKLOG_PREFLIGHT}}
+```
+
+If the backlog provider is unavailable, stop and inform the user.
+
+---
+
+## Execution
+
+Launch a **single** sr-product-analyst agent (`subagent_type: sr-product-analyst`) to read and prioritize the backlog.
+
+The product-analyst receives this prompt:
+
+> You are reading the product-driven backlog from {{BACKLOG_PROVIDER_NAME}} and producing a prioritized view.
+
+1. **Fetch all open product-driven backlog items:**
+   ```bash
+   {{BACKLOG_FETCH_CMD}}
+   ```
+
+2. **Parse each issue/ticket** to extract metadata from the body:
+   - **Area**: from `area:*` label
+   - **Persona Fit**: from the body's Overview table — extract per-persona scores and total
+   - **Effort**: from the body's Overview table (High/Medium/Low)
+   - **Description**: from the body's "Feature Description" section
+   - **User Story**: from the body's "User Story" section
+
+3. **Parse prerequisites for each issue:**
+   - Locate the row whose first cell matches `**Prerequisites**` in the issue body's Overview table.
+   - If the cell value is `None`, `-`, or empty: set `prereqs = []` for this issue.
+   - Otherwise: extract all tokens matching `#\d+` from the cell and set `prereqs = [<numbers>]`.
+   - If a prerequisite number does not appear in the fetched issue list, treat it as already satisfied (externally closed). Do not include it in the DAG.
+
+4. **Build dependency graph and detect cycles:**
+   - Construct a directed graph where edge `(A → B)` means "issue A must complete before issue B".
+   - For each issue with a non-empty `prereqs` list, add an edge from each prerequisite to the issue.
+   - Run depth-first cycle detection:
+     - Maintain `visited` and `rec_stack` sets.
+     - For each unvisited node, run DFS. If a node in `rec_stack` is encountered, a cycle exists.
+   - Collect all cycle members into `CYCLE_MEMBERS`.
+   - If `CYCLE_MEMBERS` is non-empty, prepare a warning block to render before the backlog table:
+     ```
+     > **Warning: Circular dependency detected in backlog.**
+     > The following issues form a cycle and cannot be safely ordered:
+     > #A -> #B -> #A
+     > Review these issues and correct the Prerequisites fields.
+     ```
+   - Compute `in_degree[issue]` for all issues (count of prerequisite edges pointing to each issue from other open backlog issues).
+
+5. **Compute safe implementation order (Kahn's topological sort):**
+   - Exclude `CYCLE_MEMBERS` from this computation.
+   - Initialize `ready` = all non-cycle issues where `in_degree == 0`.
+   - Sort `ready` by Total Persona Score descending.
+   - Build `WAVES = []`:
+     ```
+     while ready is non-empty:
+         WAVES.append(copy of ready)
+         next_ready = []
+         for each issue in ready:
+             for each dependent D of issue (edges issue → D):
+                 in_degree[D] -= 1
+                 if in_degree[D] == 0: next_ready.append(D)
+         sort next_ready by Total Persona Score descending
+         ready = next_ready
+     ```
+   - Store `WAVE_1 = WAVES[0]` (the set of immediately startable features).
+
+6. **Group by area**.
+
+7. **Sort within each area by Total Persona Score (descending)**, then by Effort (Low > Medium > High) as tiebreaker.
+
+8. **Display** as a formatted table per area, then **propose the top 3 items from `WAVE_1`** (features with all prerequisites satisfied) for implementation. If fewer than 3 are in `WAVE_1`, show as many as available and add: "Note: Only {N} feature(s) are available to start immediately — remaining features have unmet prerequisites."
+
+   [If `CYCLE_MEMBERS` is non-empty, render the cycle warning block immediately before the first area table.]
+
+   Render each area table with the following format:
+   - Append `[blocked]` to the issue title cell if `in_degree[issue] > 0` and the issue is not in `CYCLE_MEMBERS`.
+   - Append `[cycle]` to the issue title cell if the issue is in `CYCLE_MEMBERS`.
+   - `Prereqs` cell: list prerequisite issue numbers as `#N, #M`, or `—` if none.
+
+   ```
+   ## Product-Driven Backlog
+
+   {N} open issues | Source: VPC-based product discovery
+   Personas: {{PERSONA_NAMES_WITH_ROLES}}
+
+   ### {Area Name}
+
+   | # | Issue | {{PERSONA_SCORE_HEADERS}} | Total | Effort | Prereqs |
+   |---|-------|{{PERSONA_SCORE_SEPARATORS}}|-------|--------|---------|
+   | 1 | #42 Feature name [blocked] | ... | X/{{MAX_SCORE}} | Low | #12, #17 |
+   | 2 | #43 Other feature | ... | X/{{MAX_SCORE}} | High | — |
+
+   ---
+
+   ## Recommended Next Sprint (Top 3)
+
+   Ranked by VPC persona score / effort ratio:
+
+   | Priority | Issue | Area | {{PERSONA_SCORE_HEADERS}} | Total | Effort | Rationale |
+   |----------|-------|------|{{PERSONA_SCORE_SEPARATORS}}|-------|--------|-----------|
+
+   ### Selection criteria
+   - Cross-persona features (both 4+/5) prioritized over single-persona
+   - Low effort preferred over high effort at same score
+   - Critical pain relief weighted higher than gain creation
+
+   Run `/sr:implement` to start implementing these items.
+   ```
+
+9. **Render Safe Implementation Order section** after the Recommended Next Sprint table:
+
+   ```
+   ---
+
+   ## Safe Implementation Order
+
+   Features grouped by wave. All features in a wave can start in parallel.
+   Features in wave N must complete before wave N+1 begins.
+
+   | Wave | Issue | Title | Prereqs | Score | Effort |
+   |------|-------|-------|---------|-------|--------|
+   | 1    | #N    | ...   | —       | X/{{MAX_SCORE}} | Low |
+   | 2    | #M    | ...   | #N      | X/{{MAX_SCORE}} | Medium |
+
+   To implement in this order:
+     /sr:batch-implement <issue-refs in wave order> --deps "<A> -> <B>, <C> -> <D>, ..."
+
+   [If no edges exist in the DAG, omit the --deps clause:]
+     /sr:batch-implement <issue-refs>
+
+   [If CYCLE_MEMBERS is non-empty, append:]
+   Cycle members excluded from ordering: #A, #B
+   Fix the Prerequisites fields in these issues to include them.
+   ```
+
+   Issue refs in the `/sr:batch-implement` command are listed in wave order (wave 1 first, then wave 2, etc.), sorted by persona score within each wave. The `--deps` string is constructed from all edges in the DAG: `"A -> B"` for each edge, comma-separated. If the backlog has no dependencies at all (DAG has no edges), the section still renders showing all features in wave 1 and the `--deps` clause is omitted.
+
+10. If no issues exist:
+    ```
+    No product-driven backlog issues found. Run `/sr:update-product-driven-backlog` to generate feature ideas.
+    ```
+
+7. **[Orchestrator]** After the product-analyst completes, write issue snapshots to `.claude/backlog-cache.json`.
+
+   **Guard:** If `GH_AVAILABLE=false` (from Phase 0 pre-flight), print `[backlog-cache] Skipped — GH unavailable.` and return. Do not attempt the write.
+
+   **Fetch all open backlog issues in one call:**
+
+   ```bash
+   gh issue list --label "product-driven-backlog" --state open --json number,title,state,assignees,labels,body,updatedAt
+   ```
+
+   For each issue in the result, build a snapshot object:
+   - `number`: integer issue number
+   - `title`: issue title string
+   - `state`: `"open"` or `"closed"`
+   - `assignees`: array of assignee login names, sorted alphabetically
+   - `labels`: array of label names, sorted alphabetically
+   - `body_sha`: SHA-256 of the raw body string — compute with:
+     ```bash
+     echo -n "{body}" | sha256sum | cut -d' ' -f1
+     ```
+     If `sha256sum` is not available, fall back to `openssl dgst -sha256 -r` or `shasum -a 256`.
+   - `updated_at`: the `updatedAt` value from the GitHub API response
+   - `captured_at`: current local time in ISO 8601 format
+
+   **Merge strategy:** If `.claude/backlog-cache.json` already exists and is valid JSON, read it and merge: new snapshot entries overwrite existing entries by issue number key; entries for issue numbers not in the current fetch are preserved (they may be needed by an in-progress `/sr:implement` run). If the file does not exist or is malformed, create it fresh.
+
+   Write the merged result back to `.claude/backlog-cache.json` with:
+   - `schema_version`: `"1"`
+   - `provider`: `"github"`
+   - `last_updated`: current ISO 8601 timestamp
+   - `written_by`: `"product-backlog"`
+   - `issues`: the merged map keyed by string issue number
+
+   If the write fails (e.g., `.claude/` directory does not exist): print `[backlog-cache] Warning: could not write cache. Continuing.` Do not abort.

package/templates/skills/sr-refactor-recommender/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: sr-refactor-recommender
+description: "sr:refactor-recommender — Scan the codebase for refactoring opportunities ranked by impact/effort ratio. Optionally creates GitHub Issues for tracking."
+license: MIT
+compatibility: "Requires git."
+metadata:
+  author: specrails
+  version: "1.0"
+---
+
+
+Scan the codebase for refactoring opportunities, score each by impact/effort ratio and VPC persona value, and optionally create GitHub Issues for the top findings in {{BACKLOG_PROVIDER_NAME}}.
+
+**Input:** `$ARGUMENTS` — optional: comma-separated paths to scope the analysis. Flags: `--dry-run` (print findings without creating issues).
+
+---
+
+## Phase 0: Pre-flight
+
+Check whether the GitHub CLI is available:
+
+```bash
+{{BACKLOG_PREFLIGHT}}
+```
+
+Set `GH_AVAILABLE=true` if the command succeeds, `GH_AVAILABLE=false` otherwise. Do not stop — analysis proceeds regardless. Parse `--dry-run` from `$ARGUMENTS` and set `DRY_RUN=true` if present.
+
+---
+
+## Phase 1: Scope
+
+Parse paths from `$ARGUMENTS` after stripping any flags. If no paths are provided, scan the entire repository.
+
+Always exclude the following from all analysis:
+
+- `node_modules/`
+- `.git/`
+- `.claude/`
+- `vendor/`
+- `dist/`
+- `build/`
+
+---
+
+## Phase 1.5: VPC Context
+
+Check whether persona files exist at `.claude/agents/personas/`. This path is present in any repo that has run `/setup`.
+
+```bash
+ls .claude/agents/personas/ 2>/dev/null
+```
+
+If the directory exists and contains persona files, set `VPC_AVAILABLE=true`. Otherwise set `VPC_AVAILABLE=false` and skip all VPC steps (they are optional enrichment, not blockers).
+
+When `VPC_AVAILABLE=true`, read each persona file and extract a compact VPC summary. For each persona record:
+
+- **name** — persona display name (e.g. "Alex — The Lead Dev")
+- **top_jobs** — up to 3 functional jobs relevant to code quality and maintainability
+- **critical_pains** — up to 3 pains marked Critical or High related to code reliability, complexity, or developer experience
+- **high_gains** — up to 3 gains marked High related to code clarity, speed, or confidence
+
+Store these as an in-memory `VPC_PROFILES` list. You will use it in Phase 3 to score persona fit.
+
+---
+
+## Phase 2: Analysis
+
+Analyze the scoped files across six categories. For each finding record:
+
+- **file** — relative path
+- **line_range** — start and end line numbers
+- **current_snippet** — the problematic code as-is
+- **proposed_snippet** — concrete refactored version
+- **rationale** — one sentence explaining the improvement
+
+### Duplicate Code
+
+Find code blocks larger than 10 lines that are substantially similar across two or more files. Consolidation into a shared function or module is the expected refactoring.
+
+### Long Functions
+
+Find functions or methods exceeding 50 lines. Extraction into smaller, single-purpose functions is the expected refactoring.
+
+### Large Files
+
+Find files exceeding 300 lines. Splitting into cohesive modules is the expected refactoring.
+
+### Dead Code
+
+Find unused exports, unreferenced functions, and commented-out blocks that have not been active for the lifetime of the file. Deletion or archival is the expected refactoring.
+
+### Outdated Patterns
+
+Find deprecated APIs and old language syntax: `var` instead of `let`/`const`, callbacks instead of `async`/`await`, legacy framework APIs with documented replacements, etc. Modernisation to current idioms is the expected refactoring.
+
+### Complex Logic
+
+Find deeply nested conditionals (more than 3 levels) and functions with high cyclomatic complexity. Extraction, early-return guards, or strategy patterns are the expected refactoring.
+
+---
+
+## Phase 3: Score and Rank
+
+Score every finding on three dimensions (1–5 each):
+
+- **Impact** — how much the refactoring improves code quality, readability, or maintainability
+- **Effort** — how hard the refactoring is to implement (1 = trivial, 5 = major)
+- **VPC Value** — how directly this refactoring addresses persona jobs, pains, or gains (1 = no relevance, 5 = resolves a critical persona pain or delivers a high-value gain). Set to 3 when `VPC_AVAILABLE=false`.
+
+**Scoring VPC Value** (only when `VPC_AVAILABLE=true`):
+
+For each finding, reason over `VPC_PROFILES`:
+
+- Does fixing this reduce a **Critical/High pain** for any persona? (e.g. complex logic → harder to trust AI output → Alex's "agents go off the rails" pain) → score 4–5
+- Does fixing this deliver a **High gain** for any persona? (e.g. extracting a function → cleaner API surface → easier onboarding → Sara's gain) → score 3–4
+- Is there indirect persona value? (e.g. dead code removal → smaller codebase → easier contributor review → Kai) → score 2–3
+- No clear persona relevance → score 1–2
+
+Assign one `vpc_value` integer per finding, and note the **primary persona** and **rationale** (one sentence).
+
+**Composite score**: `impact * 2 + (6 - effort) + vpc_value`. Higher is better.
+
+Sort all findings by composite score descending. If the same code block was flagged by multiple categories, keep only the highest-scored entry and discard the duplicates.
+
+---
+
+## Phase 4: Create GitHub Issues
+
+Skip this phase if `GH_AVAILABLE=false` or `DRY_RUN=true`.
+
+First ensure the tracking labels exist:
+
+```bash
+gh label create "refactor-opportunity" --color "B60205" --force
+```
+
+Fetch existing open issues that already carry the label to avoid duplicates:
+
+```bash
+gh issue list --label "refactor-opportunity" --state open --limit 100 --json number,title
+```
+
+For each of the **top 5** findings (by composite score) that does not already have a matching open issue, create a GitHub Issue with the following body:
+
+```
+## Refactoring Opportunity: {description}
+
+**Category**: {category}
+**File**: {file}:{line_range}
+**Impact**: {impact}/5 | **Effort**: {effort}/5 | **Score**: {composite}
+{vpc_line}
+
+### Current Code
+```{lang}
+{current_snippet}
+```
+
+### Proposed Refactoring
+```{lang}
+{proposed_snippet}
+```
+
+### Rationale
+{rationale}
+
+---
+_Generated by `/sr:refactor-recommender` in {{PROJECT_NAME}}_
+```
+
+Where `{vpc_line}` is included only when `VPC_AVAILABLE=true`:
+`**VPC Value**: {vpc_value}/5 — {vpc_persona}: {vpc_rationale}`
+
+---
+
+## Phase 5: Output Summary
+
+Print the following report:
+
+```
+## Refactoring Opportunities — {{PROJECT_NAME}}
+
+{N} opportunities found | Sorted by composite score
+{vpc_header}
+
+| # | Category | File | Impact | Effort | VPC | Score | Description |
+|---|----------|------|--------|--------|-----|-------|-------------|
+| 1 | {category} | {file}:{line_range} | {impact}/5 | {effort}/5 | {vpc_value}/5 | {composite} | {description} |
+...
+
+### Top 3 Detailed Recommendations
+
+#### 1. {description}
+**File**: {file}:{line_range}
+**Category**: {category} | **Score**: {composite}
+{vpc_detail}
+
+**Current:**
+```{lang}
+{current_snippet}
+```
+
+**Proposed:**
+```{lang}
+{proposed_snippet}
+```
+
+**Rationale:** {rationale}
+
+(repeat for #2 and #3)
+
+Issues created: {N}  (or "dry-run: no issues created")
+```
+
+Where:
+- `{vpc_header}` is `VPC personas loaded: {persona names}` when `VPC_AVAILABLE=true`, or `VPC personas: not found (run /setup to enable)` otherwise.
+- `{vpc_detail}` is `**VPC Value**: {vpc_value}/5 — {vpc_persona}: {vpc_rationale}` when `VPC_AVAILABLE=true`, omitted otherwise.

package/templates/skills/sr-update-backlog/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: sr-update-backlog
+description: "sr:update-product-driven-backlog — Generate new feature ideas through product discovery, create GitHub Issues."
+license: MIT
+compatibility: "Requires GitHub CLI (gh)."
+metadata:
+  author: specrails
+  version: "1.0"
+---
+
+
+Analyze the project from a **product perspective** to generate new feature ideas. Syncs results to GitHub Issues labeled `product-driven-backlog`. Use `/sr:product-backlog` to view current ideas.
+
+**Input:** $ARGUMENTS (optional: comma-separated areas to focus on. If empty, analyze all areas.)
+
+**IMPORTANT: This command only creates GitHub Issues.** You may read files and search code to understand current capabilities, but you must NEVER write application code.
+
+---
+
+## Areas
+
+{{AREA_TABLE}}
+
+---
+
+## Execution
+
+Launch a **single** explorer subagent (`subagent_type: Explore`, `run_in_background: true`) for product discovery.
+
+The Explore agent receives this prompt:
+
+> You are a product strategist analyzing the {{PROJECT_NAME}} project to generate new feature ideas using the **Value Proposition Canvas** framework.
+>
+> **Your goal:** For each area, propose 2-4 new features that would significantly improve the user experience. Every feature MUST be evaluated against the project's personas.
+>
+> **Areas to analyze:** {all areas or filtered by user input}
+>
+> ### Step 0: Read Personas
+>
+> **Before anything else**, read all persona files:
+> {{PERSONA_FILE_READ_LIST}}
+>
+> These contain full Value Proposition Canvas profiles (jobs, pains, gains).
+>
+> ### Research steps
+>
+> 1. **Understand current capabilities** — Read codebase structure
+> 2. **Check existing backlog** — Avoid duplicating existing issues
+> 3. **Think through each persona's day** — For each area:
+>    - What does each persona need here?
+>    - What would a competitive tool offer?
+>    - What data is available but not surfaced?
+>
+> 4. **For each idea, produce a VPC evaluation:**
+>    - **Feature name** (short, descriptive)
+>    - **User story** ("As a [user type], I want to [action] so that [benefit]")
+>    - **Feature description** (2-3 sentences)
+>    - **VPC Fit** per persona: Jobs, Pains relieved, Gains created, Score (0-5)
+>    - **Total Persona Score**: sum of all persona scores / max possible
+>    - **Effort** (High/Medium/Low)
+>    - **Inspiration** (competitor or product pattern)
+>    - **Prerequisites**
+>    - **Area**
+
+---
+
+## Assembly — Backlog Sync
+
+After the Explore agent completes:
+
+1. **Display** results to the user.
+
+2. Read `.claude/backlog-config.json` and extract:
+   - `BACKLOG_PROVIDER` (`github`, `jira`, or `none`)
+   - `BACKLOG_WRITE` (from `write_access`)
+
+### If `BACKLOG_WRITE=false` — Display only (no sync)
+
+3. **Display all proposed features** in a structured format so the user can manually create tickets:
+
+   ```
+   ## Product Discovery Results (not synced)
+
+   Backlog access is set to **read-only**. The following features were discovered
+   but NOT created in {{BACKLOG_PROVIDER_NAME}}. Create them manually if desired.
+
+   ### Feature 1: {name}
+   - **Area:** {area}
+   - **Persona Fit:** {{PERSONA_FIT_FORMAT}}
+   - **Effort:** {level}
+   - **User Story:** As a {user}, I want to {action} so that {benefit}
+   - **Description:** {2-3 sentences}
+
+   (repeat for each feature)
+
+   ### Summary
+   | # | Feature | {{PERSONA_SCORE_HEADERS}} | Total | Effort |
+   |---|---------|{{PERSONA_SCORE_SEPARATORS}}|-------|--------|
+   | 1 | ... | ... | ... | ... |
+   ```
+
+4. **Do NOT** create, modify, or comment on any issues/tickets.
+
+### If provider=github and BACKLOG_WRITE=true — Sync to GitHub Issues
+
+3. **Fetch existing product-driven backlog items** to avoid duplicates:
+   ```bash
+   {{BACKLOG_FETCH_ALL_CMD}}
+   ```
+
+4. **Initialize backlog labels/tags** (idempotent):
+   ```bash
+   {{BACKLOG_INIT_LABELS_CMD}}
+   ```
+
+5. **For each proposed feature, create a backlog item** (skip duplicates):
+   ```bash
+   {{BACKLOG_CREATE_CMD}}
+   > **This is a product feature idea.** Generated through VPC-based product discovery.
+
+   ## Overview
+
+   | Field | Value |
+   |-------|-------|
+   | **Area** | {Area} |
+   | **Persona Fit** | {{PERSONA_FIT_FORMAT}} |
+   | **Effort** | {High/Medium/Low} — {justification} |
+   | **Inspiration** | {source or "Original idea"} |
+   | **Prerequisites** | {list or "None"} |
+
+   ## User Story
+
+   As a **{user type}**, I want to **{action}** so that **{benefit}**.
+
+   ## Feature Description
+
+   {2-3 sentence description}
+
+   ## Value Proposition Canvas
+
+   {{PERSONA_VPC_SECTIONS}}
+
+   ## Implementation Notes
+
+   {Brief notes on existing infrastructure and what needs to be built}
+
+   ---
+   _Auto-generated by `/sr:update-product-driven-backlog` on {DATE}_
+   EOF
+   )"
+   ```
+
+6. **Report** sync results:
+   ```
+   Product discovery complete:
+   - Created: {N} new feature ideas in GitHub Issues
+   - Skipped: {N} duplicates (already exist)
+   ```
+
+### If provider=jira and BACKLOG_WRITE=true — Sync to JIRA
+
+Read from `.claude/backlog-config.json`:
+- `JIRA_BASE_URL`, `JIRA_PROJECT_KEY`, `AUTH_METHOD`
+- `PROJECT_LABEL` (may be empty string)
+- `EPIC_MAPPING` (object mapping area name → JIRA epic key)
+- `EPIC_LINK_FIELD` (default: `"parent"`)
+- `CLI_INSTALLED`
+
+#### Step A: Authenticate
+
+If `AUTH_METHOD=api_token`: require env vars `JIRA_USER_EMAIL` and `JIRA_API_TOKEN`.
+If either is missing:
+```
+Error: JIRA_USER_EMAIL and JIRA_API_TOKEN must be set in your environment.
+See: https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/
+```
+Stop and do not proceed with sync.
+
+#### Step B: Fetch existing JIRA stories (duplicate check)
+
+```bash
+curl -s \
+  -H "Authorization: Basic $(printf '%s' "$JIRA_USER_EMAIL:$JIRA_API_TOKEN" | base64)" \
+  -H "Content-Type: application/json" \
+  "${JIRA_BASE_URL}/rest/api/3/search?jql=project%3D${JIRA_PROJECT_KEY}+AND+labels%3Dproduct-backlog+AND+issuetype%3DStory&fields=summary&maxResults=200"
+```
+
+Store all `summary` values. Skip any feature whose title matches an existing summary.
+
+#### Step C: Group features by area
+
+From the Explore agent output, group features into `area -> [features]`.
+Area names: strip the `area:` prefix (e.g., `area:core` → `core`).
+
+#### Step D: Ensure epics exist per area
+
+For each unique area:
+
+1. **Cache hit:** If `EPIC_MAPPING[area]` is set: use that key. Proceed to Step E.
+
+2. **JIRA search:** Search for existing epic:
+   ```bash
+   curl -s \
+     -H "Authorization: Basic $(printf '%s' "$JIRA_USER_EMAIL:$JIRA_API_TOKEN" | base64)" \
+     -H "Content-Type: application/json" \
+     "${JIRA_BASE_URL}/rest/api/3/search?jql=project%3D${JIRA_PROJECT_KEY}+AND+issuetype%3DEpic+AND+summary+%7E+%22${AREA_NAME}%22&fields=summary,key"
+   ```
+   If found: set `EPIC_MAPPING[area] = <key>`. Proceed to Step E.
+
+3. **Create epic:**
+   ```bash
+   curl -s -X POST \
+     -H "Authorization: Basic $(printf '%s' "$JIRA_USER_EMAIL:$JIRA_API_TOKEN" | base64)" \
+     -H "Content-Type: application/json" \
+     "${JIRA_BASE_URL}/rest/api/3/issue" \
+     --data '{
+       "fields": {
+         "project": {"key": "'"${JIRA_PROJECT_KEY}"'"},
+         "issuetype": {"name": "Epic"},
+         "summary": "'"${AREA_DISPLAY_NAME}"'",
+         "labels": ["product-backlog"]
+       }
+     }'
+   ```
+   If `PROJECT_LABEL` is non-empty, add it to the `labels` array.
+   Set `EPIC_MAPPING[area] = <returned key>`.
+
+After all areas are processed: write the updated `EPIC_MAPPING` back to `.claude/backlog-config.json`.
+
+#### Step E: Create Story tickets
+
+For each feature not in the duplicate list:
+
+```bash
+curl -s -X POST \
+  -H "Authorization: Basic $(printf '%s' "$JIRA_USER_EMAIL:$JIRA_API_TOKEN" | base64)" \
+  -H "Content-Type: application/json" \
+  "${JIRA_BASE_URL}/rest/api/3/issue" \
+  --data '{
+    "fields": {
+      "project": {"key": "'"${JIRA_PROJECT_KEY}"'"},
+      "issuetype": {"name": "Story"},
+      "summary": "'"${FEATURE_NAME}"'",
+      "description": {
+        "type": "doc",
+        "version": 1,
+        "content": [{
+          "type": "codeBlock",
+          "content": [{"type": "text", "text": "'"${VPC_BODY_ESCAPED}"'"}]
+        }]
+      },
+      "labels": ["product-backlog"],
+      "'"${EPIC_LINK_FIELD}"'": {"key": "'"${EPIC_KEY}"'"}
+    }
+  }'
+```
+
+If `PROJECT_LABEL` is non-empty: add it to the `labels` array.
+`VPC_BODY_ESCAPED`: the full VPC markdown body with double quotes escaped (`"`→`\"`).
+
+**Error handling:**
+- If the API returns an error about the epic key (dead key): log a warning, create the story without epic linkage, continue.
+- Any other API error: log the error message and story name, continue to next story.
+
+#### Step F: Report results
+
+```
+JIRA sync complete:
+- Epics created: {N} (area names)
+- Epics reused: {N} (area names)
+- Stories created: {N}
+- Stories skipped (duplicates): {N}
+- Stories without epic (errors): {N}
+- Project label applied: {PROJECT_LABEL} / (none — label was empty)
+```