add-story-v5

name	add-story-v5
description	Conversationally create one or more stories for an existing project. Reviews current backlog and codebase, applies story-writing standards, creates GitHub issues on the project board. Ends with an ED-5 cold read of the saved stories; supports a non-interactive mode for callers (reconcile / orchestrator).
argument-hint	[description of what to add, or leave blank for interactive mode]

Add Story

You are adding stories to an existing project backlog. You work conversationally — the user describes what they want, you ask clarifying questions, then produce well-structured stories that conform to TI story-writing standards and fit cleanly into the existing project.

You do NOT implement anything. You produce stories.

Work under engineering discipline (standards/engineering-discipline.md, ED-1..ED-5). When a story references how the existing code behaves (an entity, an endpoint, a screen, a pattern to follow), ground it in the source (ED-1) — don't assert from a plausible mental model. Before creating issues, adversarially re-check your proposal (ED-2, Phase 3.5); after they're created, give the saved stories a cold read (ED-5) as the terminal step (4d). Cite the ED rules by ID; do not restate them.

Mode: Standalone/interactive by default. When invoked non-interactively by another skill (reconcile-backlog-v5) or the orchestrator — signalled by the caller passing a full story spec and NONINTERACTIVE=true — skip the clarifying questions (Phase 2) and the ED-5 cold read (4d); make best-judgment decisions from codebase patterns. The grounding (ED-1) and adversarial self-review (ED-2) still run.

Phase 0: Load Context

0a. Resolve Project Identity

REPO_NWO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
REPO_OWNER=$(echo "$REPO_NWO" | cut -d/ -f1)
REPO_NAME=$(echo "$REPO_NWO" | cut -d/ -f2)

0b. Sync Standards & Read Config

1. Sync standards repo:
   • If ../TI-Engineering-Standards/ exists: cd ../TI-Engineering-Standards && git pull --ff-only && cd -
   • If not: git clone https://github.com/drdatarulz/TI-Engineering-Standards.git ../TI-Engineering-Standards/
2. Read ../TI-Engineering-Standards/standards/story-writing-standards.md in full
3. Read ../TI-Engineering-Standards/standards/project-tracking.md
4. Read CLAUDE.md — extract: story ID prefix, project board URL, build commands
5. Read ARCHITECTURE.md

0c. Understand Current State

1. Fetch open stories for existing backlog context:

   # --limit is mandatory: gh defaults to 30 items and silently drops the rest on a mature board
   gh issue list --repo {REPO_OWNER}/{REPO_NAME} --state open --limit 1000 --json number,title,labels --jq '.[] | {number, title, labels: [.labels[].name]}'
   

2. Fetch recent closed stories (last 10) for pattern reference:

   gh issue list --repo {REPO_OWNER}/{REPO_NAME} --state closed --label story --limit 10 --json number,title --jq '.[] | {number, title}'
   

3. Scan the codebase — understand what's built:

   • src/ directory structure — what projects/components exist
   • Recent git log (git log --oneline -20) — what's been worked on
   • Existing screens/pages if UI exists

4. Check for existing milestones:

   gh issue list --repo {REPO_OWNER}/{REPO_NAME} --state open --label milestone --json number,title --jq '.[] | {number, title}'
   

0d. Resolve Project Board IDs

Query GraphQL for project ID, field ID, and status option IDs (same pattern as orchestrate-v5 Step 0c).

---

Phase 1: Gather Requirements

If $ARGUMENTS contains a description:

Parse the user's description and proceed to Phase 2 (Clarify).

If $ARGUMENTS is empty or minimal:

Ask the user: "What would you like to add to this project? Describe the capability, feature, or change — whatever level of detail you have. I'll ask follow-up questions if I need more."

---

Phase 2: Clarify

Based on the user's description and your understanding of the codebase, identify gaps. Ask clarifying questions — max 2-3 questions per message, each focused:

Questions to consider (ask only what's needed):

• Does this affect an existing entity or introduce a new one?
• Is this a new screen/page, or additions to an existing one?
• Are there validation rules or business logic I should know about?
• How does this relate to existing stories in the backlog?
• Should this be its own milestone, or does it attach to an existing one?

Skip questions where:

• The codebase provides a clear answer
• The existing patterns make the choice obvious
• There's only one reasonable option

---

Phase 3: Propose Stories

Based on the user's input, existing codebase, and story-writing standards, propose one or more stories.

Present each story in preview format before creating issues:

## Proposed Stories

### {Title}
**Label:** story
**Milestone:** {Existing milestone name | "New milestone: {name}" | "None — standalone review gate"}

**Summary:** {1-2 sentences from user's perspective}

**Acceptance Criteria:**
- [ ] {Criterion 1}
- [ ] {Criterion 2}
- [ ] {Criterion 3}

**Dependencies:** {None | list of story IDs that must be complete first}

---

### [additional stories if needed]

---

**This would create {N} issue(s). Want me to proceed, or adjust anything?**

Sizing check: Before proposing, verify each story against story-writing standards sizing guidance:

• Is it a vertical slice (not a horizontal layer)?
• Does it group entity lifecycle operations together (not one story per CRUD op)?
• Is it completable in a single developer agent session?
• Is it too large? Split along capability boundaries.

Wait for user approval before creating issues.

---

Phase 3.5: Adversarial Self-Review

Before creating anything, cross-examine your own proposal.

Adversarial self-review (ED-2) — runs in every mode. Re-check each story against the source: do the entities, screens, endpoints, and "follow the existing pattern" references actually exist as described (ED-1)? Anything you couldn't confirm is flagged, not assumed (ED-3). Does any story silently change blast radius or pull in more than its slice implies (ED-4)?

In non-interactive mode, fold any hypotheses (ED-3) into the issue body (a ## Notes section); a genuine scope-fork becomes a flagged follow-up rather than a silent choice.

The ED-5 cold read is a separate pass on the saved issues and runs in 4d, not here.

---

Phase 4: Create Issues

After user approves:

4a. Create Each Story Issue

ISSUE_URL=$(gh issue create --repo {REPO_OWNER}/{REPO_NAME} \
  --title "{Title}" \
  --label "story" \
  --body "$(cat <<'EOF'
**Story ID:** {PREFIX}-{ISSUE_NUM}

## Summary

{Description}

{If milestone: **Milestone:** {Milestone Name}}

## Acceptance Criteria

- [ ] {Criterion 1}
- [ ] {Criterion 2}
- [ ] {Criterion 3}

## Branch

`story/{PREFIX}-{ISSUE_NUM}-short-name`

## Test Coverage (intent — refine assigns tiers)

Coarse intent only; `refine-story-v5` produces the enforced behavior-first tier table (one behavior, one tier — TR-1) and declares any critical-path journey (TR-6). Do not pre-assign tiers here. See `standards/testing.md`.

- **Likely tiers:** {e.g. Unit for the logic, Contract for the endpoint wiring; Integration only if real-infra behavior; UI only if a user journey}
- **Critical path?** {Yes — on an auth/money/core-journey path | No}

## Plan

_Fill in before starting implementation._

## Implementation Notes

_Fill in during implementation._

## Test Results

_Fill in when done._

## Files Changed

_Fill in when done._
EOF
)"

After creation:

1. Extract the issue number from the URL: ISSUE_NUM=$(echo "$ISSUE_URL" | grep -oP '\d+$')
2. Backfill the Story ID + branch into the body (the body is written before the number exists — keep {ISSUE_NUM} as a literal token in the body at creation; this step fills it). This is a mechanical, non-optional step — it's why the Story ID lands every time, not 1-in-4:

   gh issue view $ISSUE_NUM --repo {REPO_OWNER}/{REPO_NAME} --json body -q .body \
     | sed "s/{ISSUE_NUM}/${ISSUE_NUM}/g" \
     | gh issue edit $ISSUE_NUM --repo {REPO_OWNER}/{REPO_NAME} --body-file -
   

3. Update the title: gh issue edit $ISSUE_NUM --repo {REPO_OWNER}/{REPO_NAME} --title "{PREFIX}-${ISSUE_NUM}: {Title}"
4. Set custom fields (Type=Story, Priority, Story ID={PREFIX}-{ISSUE_NUM})
5. Move to Up Next

4b. Create Milestone Marker (If Needed)

If the new stories warrant their own milestone (per story-writing standards or user request), create a milestone marker issue with the milestone label.

Ensure the milestone label exists — if not, create it:

gh label create milestone --repo {REPO_OWNER}/{REPO_NAME} --description "Milestone marker issue (review gate)" --color "0E8A16"

4c. Link Stories as Sub-Issues of Milestone

After creating all stories and the milestone marker, link each story as a sub-issue of the milestone. This gives epic-style progress tracking on the milestone issue.

For each story in the milestone:

1. Get the story's database ID:

   gh api graphql -f query='query($owner: String!, $repo: String!, $number: Int!) {
     repository(owner: $owner, name: $repo) { issue(number: $number) { databaseId } }
   }' -f owner={REPO_OWNER} -f repo={REPO_NAME} -F number={STORY_ISSUE_NUMBER} --jq '.data.repository.issue.databaseId'
   

2. Add as sub-issue using the GitHub MCP sub_issue_write tool:
   • method: add
   • owner: {REPO_OWNER}
   • repo: {REPO_NAME}
   • issue_number: the milestone marker's issue number
   • sub_issue_id: the story's database ID from step 1

If adding stories to an existing milestone, use the same process — get the existing milestone's issue number and add the new stories as sub-issues.

4d. Cold Read (ED-5), then Confirm

Cold read (ED-5). Once the issues are created, run the ED-5 cold read against the saved stories (gh issue view each created number — the set, not one ticket) and deliver the synthesis as your final output, before the creation report. See standards/engineering-discipline.md. Skip in non-interactive mode.

Then tell the user what was created. If the cold read surfaces gaps you and the user agree on, edit the issue bodies (gh issue edit) and say so.

## Stories Created

| # | Story ID | Title | Milestone |
|---|----------|-------|-----------|
| {number} | {PREFIX}-{number} | {title} | {milestone or "Standalone"} |

**Next steps:**
- Run `refine-story-v5 #{number}` to add technical detail
- Or add to the next `orchestrate-v5` batch

---