edercnj/x-add-story-to-feature

Output Policy

• Efficiency: Avoid repeating Product-First rationale already captured in parent artifacts.

Skill: x-add-story-to-feature

Purpose

Add a newly discovered (post-refinement) story to an existing, already-refined feature. This skill:

1. Validates that the target feature exists and has an approved refinement verdict.
2. Generates the new story file via x-internal-create-story-from-feature (when --from-feature is provided) or the inline generic story-creation procedure (generic fallback — ver references/full-protocol.md).
3. Performs an impact analysis on the feature: verifies whether the new story affects scope (§5), story index (§6), quality gates (§8), or dependencies.
4. Proposes necessary updates to the feature markdown and IMPLEMENTATION-MAP.md.
5. Applies approved changes and commits everything in a single commit.

Prerequisite: The feature must have refinementVerdict.status == "approved". This skill enforces the post-refinement discovery flow.

When to Use

• A story was discovered after the feature was already refined and approved (discovery during sprint, spike findings, etc.)
• Need to add a story scope that was intentionally deferred from initial decomposition
• Want to track the impact of the new story on the existing feature artifacts

When NOT to Use

• The feature has not been refined yet — run x-refine-feature first
• Want to generate all initial stories in bulk — that is handled by x-create-feature Stage 3
• Want to add a story that is actually a new Feature (create a new feature instead)

Parameters

| Parameter | Required | Description | | :--- | :--- | :--- | | --feature-id <NNNN> | Yes | Target feature identifier (4 digits) | | --story-title <title> | Yes | Short descriptive title for the new story | | --from-feature <path> | No | Feature markdown to derive the story from (with RNF inheritance) | | --dry-run | No | Run impact analysis and story generation without writing files |

Exit Codes

| Code | Name | Condition | |------|------|-----------| | 0 | SUCCESS | Story added and feature/map updated | | 1 | FEATURE_NOT_FOUND | Feature markdown not found | | 2 | FEATURE_NOT_REFINED | Feature does not have refinementVerdict.status == "approved" | | 3 | STORY_CREATE_FAILED | x-internal-create-story-from-feature or the inline generic story-creation procedure failed | | 4 | COMMIT_FAILED | x-commit-planning returned non-zero |

Workflow

Phase 0 — Prerequisite Validation

1. Resolve feature-NNNN-*/feature-NNNN.md glob (→ FEATURE_NOT_FOUND on miss).
2. Read feature-NNNN-*/execution-state.json. Check refinementVerdict.status == "approved" (→ FEATURE_NOT_REFINED if not).
3. Determine the next available story number for this feature (scan existing story-NNNN-*.md files).

Phase 1 — Story Generation

If --from-feature <path> provided:

Skill(skill: "x-internal-create-story-from-feature",
      args: "--from-feature {featurePath} --feature-id <NNNN> --no-commit")

Otherwise, run the inline generic story-creation procedure with the feature as both spec and feature source, in --no-commit mode (this skill owns the commit in Phase 5):

Execute o procedimento §Story Creation Procedure (âncoras CS1–CS5 + preludes/epilogue) em references/full-protocol.md, equivalente a {featurePath} {featurePath} --feature-id <NNNN> --story-title <title> --no-commit. Em --no-commit, as âncoras CS-P2/CS-P4/CS-P5 (branch-ensure/commit/push) são no-ops. O procedimento preserva as chamadas aninhadas a skills KEEP inalteradas: x-internal-select-knowledge (seleção dinâmica de knowledge --kind domain --stage story, ver CS-Prerequisites), x-commit-planning (CS-P4) e x-push-branch (CS-P5).

On failure within the procedure (quality gate exhausted, template/spec/feature missing) → exit STORY_CREATE_FAILED.

Phase 2 — Feature Impact Analysis

Read the generated story and the current feature markdown. Analyze whether the new story:

1. Scope (§5): Is the story fully within the existing in-scope? If it adds scope, propose an update to the in-scope list and verify out-of-scope is still accurate.
2. Story Index (§6): Add the new story to the feature's story index table with its estimated phase.
3. Dependencies: Does the new story depend on existing stories, or do existing stories now depend on it? Identify dependency direction.
4. Quality Gates (§8): Does the new story introduce additional DoR/DoD criteria?
5. Implementation Map: Is the implementation map's phase layout still valid? If the new story introduces dependencies that shift the critical path, note the changes.

Phase 3 — Propose Changes to Operator

Present a structured summary of proposed updates:

📋 Impact Analysis — New story: <story-title>

Story file: story-NNNN-YYYY.md ✅ created

Proposed feature updates:
  § 5 (Scope): [UPDATE required | no change] — <reason>
  § 6 (Story Index): [UPDATE required] — add row: | story-NNNN-YYYY | <title> | Phase N |
  § 7 (Dependencies): [UPDATE required | no change] — <dependency relationships>
  § 8 (Quality Gates): [UPDATE required | no change] — <new DoR/DoD criteria if any>

Proposed IMPLEMENTATION-MAP updates:
  [UPDATE required | no change] — <brief description of phase/critical path changes>

Present via AskUserQuestion with 3 choices:

• A: Apply all proposed changes (Recommended)
• B: Review changes individually
• C: Skip feature/map updates (story file only)

Phase 4 — Apply Updates

Based on operator choice:

Option A (Apply all):

• Edit feature markdown: update §5, §6, §7, §8 as proposed
• Edit IMPLEMENTATION-MAP.md: add new story to phase layout and dependencies

Option B (Individual review):

• For each proposed change, ask confirmation before applying

Option C (Skip):

• Only the story file is saved; feature and map are left unchanged
• Print WARNING: "Feature markdown and IMPLEMENTATION-MAP not updated. Manual review recommended."

Phase 5 — Commit

Skill(skill: "x-commit-planning",
      args: "--scope chore --feature-id <NNNN> --paths <story-path>[,<feature-path>][,<map-path>] --subject \"add story: <title>\"")

On COMMIT_FAILED (exit 4): abort.

Output Summary

x-add-story-to-feature completed
  Feature: .aikittools/features/feature-NNNN-.../feature-NNNN.md
  Story:  .aikittools/features/feature-NNNN-.../story-NNNN-YYYY.md
  Map:    <updated | not updated>
  Changes applied: <list of updated sections | none>
  Next step: /x-refine-story story-NNNN-YYYY

Integration Notes

• Requires refined feature: Will abort with FEATURE_NOT_REFINED if feature does not have an approved verdict.
• Uses internal generator + inline procedure: Delegates story file creation to x-internal-create-story-from-feature (preferred, Feature-derived) or runs the inline generic story-creation procedure (generic fallback; protocolo CS1–CS5 em references/full-protocol.md).
• Preserved nested KEEP skills: the inline procedure invokes x-internal-select-knowledge (dynamic domain knowledge selector), x-commit-planning (CS-P4) and x-push-branch (CS-P5) unchanged — these were NOT inlined.
• Does NOT re-run feature refinement: This skill only proposes and applies minimal feature updates. If the new story significantly changes the feature scope, the operator should consider running x-refine-feature again.
• Does NOT auto-run x-refine-story: After adding the story, the operator should run /x-refine-story story-NNNN-YYYY separately to complete the refinement cycle.

Decision Record

Introduced to address the discovery gap created when x-create-story (direct user invocation) was made internal. Provides a structured, impact-aware mechanism for post-refinement story additions that preserves feature consistency.

O protocolo completo do gerador genérico de story (CS1–CS5, preludes/epilogue P1/P2/P4/P5, quality gate, Jira flow, contratos de dados, Gherkin TPP) vive em references/full-protocol.md §Story Creation Procedure; o corpo desta skill permanece enxuto.

Full Protocol

Minimum viable contract above. The full generic story-creation procedure inlined from x-internal-create-story (section-by-section story template, Gherkin TPP ordering, data contract precision rules, Mermaid diagram templates, quality gate scoring dimensions, Jira cascaded vs standalone flow, sizing heuristics, common mistakes, and the preserved nested KEEP-skill calls x-internal-select-knowledge / x-commit-planning / x-push-branch) lives in references/full-protocol.md per ADR-0012 (skill body slim-by-default).