ba-story-verify
Verify that BA-authored user stories are clear enough to build, and ask the BA the missing questions on the ticket. Takes a single ticket link or a list of tickets (or a JQL result set), scores each one independently against a user-story/acceptance-criteria rubric, and drafts one comment of open questions per unclear ticket. When a comment is posted it also hands the ticket back: the reporter is @mentioned, made assignee, and the status is moved to a clarification state. Posted only after the operator approves; read-only until then, and it never plans, implements, or commits. An Epic link is routed to ba-epic-verify instead of expanded. Trigger: verify user story, check requirements clarity, is this ticket clear, ask the BA, DoR check, PROJ-123 clear enough. Do NOT load for: verifying an Epic (use ba-epic-verify), implementing a requirement (use harness-flow), bug triage (use harness-bugfix), code review, or release.
- License 许可
- MIT
- 所属仓库
- foden303/harness
- 最近更新
- 2026-11-06
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- base
- harness-flow
- kind
- workflow
- name
- ba-story-verify
- pair
- ba-epic-verify
- role
- orchestrator
- owner
- harness-core
- shape
- delegate
- since
- 2026-07-20
- effort
- high
- purpose
- Verify a ticket list against the US/AC rubric -> draft BA questions per unclear ticket -> operator approves -> post comments + hand the ticket back to its reporter -> track replies
- trigger
- verify user story, is this ticket clear, ask the BA, DoR check
- description
- Verify that BA-authored user stories are clear enough to build, and ask the BA the missing questions on the ticket. Takes a single ticket link or a list of tickets (or a JQL result set), scores each one independently against a user-story/acceptance-criteria rubric, and drafts one comment of open questions per unclear ticket. When a comment is posted it also hands the ticket back: the reporter is @mentioned, made assignee, and the status is moved to a clarification state. Posted only after the operator approves; read-only until then, and it never plans, implements, or commits. An Epic link is routed to ba-epic-verify instead of expanded. Trigger: verify user story, check requirements clarity, is this ticket clear, ask the BA, DoR check, PROJ-123 clear enough. Do NOT load for: verifying an Epic (use ba-epic-verify), implementing a requirement (use harness-flow), bug triage (use harness-bugfix), code review, or release.
- allowed-tools
- [ "Read", "Write", "Edit", "Bash", "Grep", "Glob", "Task", "AskUserQuestion", "ScheduleWakeup", "mcp__claude_ai_Atlassian_Rovo__*" ]
- argument-hint
- [<ISSUE-KEY>|<url> ...] [--jql "..."] [--ask-status "<name>"] [--no-handoff] [--resume] [--report-only] [--html] [--dry-run]
- description-en
- Verify that BA-authored user stories are clear enough to build, and ask the BA the missing questions on the ticket. Takes a single ticket link or a list of tickets (or a JQL result set), scores each one independently against a user-story/acceptance-criteria rubric, and drafts one comment of open questions per unclear ticket. When a comment is posted it also hands the ticket back: the reporter is @mentioned, made assignee, and the status is moved to a clarification state. Posted only after the operator approves; read-only until then, and it never plans, implements, or commits. An Epic link is routed to ba-epic-verify instead of expanded. Trigger: verify user story, check requirements clarity, is this ticket clear, ask the BA, DoR check, PROJ-123 clear enough. Do NOT load for: verifying an Epic (use ba-epic-verify), implementing a requirement (use harness-flow), bug triage (use harness-bugfix), code review, or release.
- user-invocable
- true
02 资源文件 4
- 参考文档references/ba-comment.md9.1 KB
- 参考文档references/report.md4.5 KB
- 参考文档references/target-list.md4.5 KB
- 参考文档references/us-rubric.md7.0 KB
03 SKILL.md 正文
ba-story-verify
The requirements-quality gate that runs before anyone starts building:
Ticket link(s) → verify each story independently → draft the open questions per ticket → operator approves → post to the BA + hand the ticket back to its reporter → track replies → re-verify.
It is the "verify + ask the BA" half of harness-flow, lifted out and scaled to
a list of stories. It stops at a clear/unclear verdict — it never plans, writes
code, or commits. When a ticket comes back clear, hand it to harness-flow to
build it.
| harness-flow | ba-story-verify | ba-epic-verify | |
|---|---|---|---|
| Unit | one feature | N independent stories | one Epic |
| Multiple links | merged into one feature | verified independently | n/a |
| Epic link | not expanded | routed out to ba-epic-verify |
the target |
| Questions | one set | one set per ticket | one set per lens (BE/FE/BA) |
| Ends at | committed change | verdict + questions on the ticket | verdict + questions on the Epic |
Core contract (read first)
- Read-only until you approve. Fetching issues and scoring them writes
nothing to JIRA. The external writes — the clarification comment and the
reporter handoff (assignee + status) — are drafted, shown to you, and sent
only on an explicit approval
(
.claude/rules/autonomous-confirmation-scope.mdcase 1). Nothing auto-posts and nothing auto-transitions. - One ticket = one verdict = one comment. Questions are never pooled across
tickets; a question about
PROJ-124is posted onPROJ-124. - Stories only. An Epic ref is routed to
ba-epic-verify, never scored here — an Epic has no acceptance criteria of its own, so these gates would fail for the wrong reasons. - Questions must trace to a failing gate. Every question in the draft comes from a gate that failed. No gate failure, no question — this keeps the BA from being asked things the ticket already answers.
- No requirement invention. When a field is missing, ask; never fill in a plausible acceptance criterion and proceed. A guessed AC is worse than a missing one because it looks answered.
- Re-entrant. Batch cursor + per-ticket records live under
.claude/state/story-verify/<batch-id>/; a re-run resumes and never re-posts a question already asked. - MCP dependency. JIRA access uses the Atlassian Rovo MCP tools. Absent
(headless/cron) → tri-state health reports
not-configuredand the skill pauses at the first step that needs it rather than guessing.
Quick Reference
| Input | Behavior |
|---|---|
/ba-story-verify PROJ-123 |
Verify that one story |
/ba-story-verify PROJ-123 PROJ-124 PROJ-125 |
Verify all three independently (not merged) |
/ba-story-verify https://<site>/browse/PROJ-123 |
Same, from a URL |
/ba-story-verify PROJ-100 (an Epic) |
Route out: recommend /ba-epic-verify PROJ-100, verify nothing |
/ba-story-verify --jql "parent = PROJ-100 AND status = 'To Do'" |
Verify the JQL result set |
/ba-story-verify PROJ-123 --ask-status "Waiting for BA" |
Force the status the handoff moves to |
/ba-story-verify PROJ-123 --no-handoff |
Comment only; do not touch assignee or status |
/ba-story-verify --resume |
Re-check for BA replies, fold them in, re-verify |
/ba-story-verify PROJ-123 --report-only |
Verify + report, never offer to post (no JIRA writes at all) |
/ba-story-verify PROJ-123 --html |
Also render the report as a single-file HTML |
/ba-story-verify PROJ-123 --dry-run |
Walk the flow, write no state and no comments |
Options
| Option | Description | Default |
|---|---|---|
<ISSUE-KEY> / <url> |
Verification target(s) — stories, not Epics | required (unless --resume / --jql) |
--jql "<query>" |
Use a JQL result set as the batch | - |
--ask-status "<name>" |
Status the handoff transitions to | matched from a candidate list |
--no-handoff |
Never change assignee or status | off (handoff on) |
--resume |
Re-check BA replies on the existing batch | - |
--report-only |
Never post; output the report only | off |
--html |
Also render story-verify-report.html |
off |
--dry-run |
No state writes, no comments | off |
--include-done |
Also verify tickets in a done/closed status | off (skipped) |
Resolving the plugin bundle root
Same as harness-flow: resolve HARNESS_PLUGIN_ROOT from CLAUDE_PLUGIN_ROOT
(if it contains scripts/), else from CLAUDE_SKILL_DIR
(${CLAUDE_SKILL_DIR}/../.., or ../../.. for a mirror). Call only
${HARNESS_PLUGIN_ROOT}/scripts/...; keep state under the host project's
.claude/state/story-verify/.
State machine
Batch cursor: .claude/state/story-verify/<batch-id>/batch.json, managed only
through ${HARNESS_PLUGIN_ROOT}/scripts/story-verify-batch.sh.
Per-ticket verdicts: .claude/state/story-verify/<batch-id>/<KEY>.json
(story-verification.v1), written only through
${HARNESS_PLUGIN_ROOT}/scripts/story-verify-record.sh.
<batch-id> is derived from the root ref (a bare list → the first key
lowercased, PROJ-101 → proj-101; --jql → jql-<n> where <n> is the
ticket count; called from ba-epic-verify --with-children → the Epic key).
[Step 0] Resolve + probe
Resolve HARNESS_PLUGIN_ROOT.
Probe MCP once:
bash "${HARNESS_PLUGIN_ROOT}/scripts/flow-mcp-health.sh" --probe <result>
(getAccessibleAtlassianResources: success -> healthy, error -> unreachable,
tools absent -> not-configured)
not-configured / unreachable -> decision_needed.v1 and STOP. Never guess.
|
v
[Step 1] Resolve targets -> batch.json
Reference: references/target-list.md
Ticket keys -> that exact list, deduped, order preserved
--jql -> the query result set
Epic key -> STOP and route to /ba-epic-verify (do not expand, do not score)
Skip done/closed tickets unless --include-done; skip sub-tasks of a listed ticket.
story-verify-batch.sh init --batch-id <id> --mode tickets \
--root <ref> --keys <k1,k2,...>
Report the target list (n in scope / n skipped and why) BEFORE verifying.
|
v
[Step 2] Verify each -> <KEY>.json (state: clear | needs-clarification | blocked)
Reference: references/us-rubric.md (13 gates, 9 blocker + 4 advisory)
Per ticket: getJiraIssue (summary, description, AC field, labels, type, status,
reporter, parent, links, attachments/design links, comments).
Score every gate to pass | fail | n-a(+note). Each failing blocker contributes
>=1 concrete question. Persist via story-verify-record.sh (it derives the
verdict from the gates — do not hand-write it).
Tickets are independent: verify all of them before asking anything.
For a batch of >=6 tickets, fan out with Task (one sub-agent per ticket,
read-only) and collect the records; <6 -> verify in-context.
|
v
[Step 3] Report Reference: references/report.md
One table: ticket | verdict | failing gates | #questions.
--html -> render a single-file HTML alongside it.
--report-only -> STOP here.
|
v
[Step 4] Approve + post + handoff state: needs-clarification -> awaiting-ba
Reference: references/ba-comment.md
Draft ONE marked comment per unclear ticket (reporter @mentioned), show ALL
drafts to the operator in one AskUserQuestion (post all / pick / edit / skip),
and post ONLY what was approved (addCommentToJiraIssue). Never auto-post.
Then per posted ticket, unless --no-handoff:
editJiraIssue assignee = reporter
transitionJiraIssue status -> the one chosen by jira-status-match.sh
A missing transition or a missing reporter is a recorded skip, never a failure.
|
v
[Step 5] Track replies state: awaiting-ba -> answered | needs-clarification
Reference: references/ba-comment.md (resume section)
ScheduleWakeup re-entry: re-fetch comments, match via flow-ba-match.sh, fold the
reply into the ticket record, re-run Step 2 for that ticket only.
Re-verify clear -> answered. Still failing -> follow-up (round cap 3) -> escalated.
|
v
[Done] All tickets terminal -> final summary + next action
story-verify-batch.sh summary <batch.json>
Stop / pause conditions
| Condition | State | Response |
|---|---|---|
| MCP not-configured / unreachable | unchanged | decision_needed.v1, stop |
| A ticket cannot be read (permission) | blocked |
Record verdict blocked, continue the rest, list them in the summary |
| The ref is an Epic | n/a | Report the type, recommend /ba-epic-verify <KEY>, stop |
| The target list is empty after filtering | n/a | Report the counts per reason and stop (do not fall back to a broader JQL) |
| Operator declines to post | needs-clarification |
Keep the draft in the report; the operator asks the BA themselves. No handoff |
| Transition unavailable | awaiting-ba |
Post + assign anyway, record transition_skipped_reason, name it in the summary |
| Reporter missing on the ticket | awaiting-ba |
Skip the assign, record assign_skipped_reason, still post and still transition |
| BA reply not yet available | awaiting-ba |
Auto-poll (ScheduleWakeup) or wait for --resume |
| Clarification round cap (3) reached | escalated |
decision_needed.v1 — proceed on a stated assumption, keep waiting, or drop |
Silence policy
Report on: the target list, per-ticket verdict, the draft set before approval,
what was posted, the handoff result per ticket (assignee + status, or why
skipped), replies folded in, final summary. Stay silent on: per-gate scoring
narration, pacing waits between reply checks with nothing new. Always end a
completed run by naming the clear/unclear/blocked counts and the next action
(hand the clear tickets to harness-flow, or wait on the open questions).
Related skills
ba-epic-verify— the Epic sibling: epic rubric + BE/FE/BA lens questionsharness-flow— build a ticket once it is verified clear (Steps 4-9 there)harness-bugfix— the bug sibling (triage vs source, QA ask-back)harness-plan— turn verified stories into Plans.md tasksharness-accept— acceptance decision after the work is delivered
04 同仓库更多 Skills
escape-skill
暂无简介
zz-review-empty
暂无简介
memory
Manage SSOT, memory, and cross-tool memory search. Guardian of decisions.md and patterns.md. Use when user mentions memory, SSOT, decisions.md, patterns.md, merging, migration, SSOT promotion, sync memory, save learnings, memory search, harness-mem, past decisions, or record this. Do NOT load for: implementation work, reviews, ad-hoc notes, or in-session logging.
maintenance
File cleanup and archiving. Tidies up bloated Plans.md, session-log.md, old logs, and state files. Trigger: /maintenance, cleanup, archive, organize, split session-log. Do NOT load for: implementation, review, release, new feature development.
harness-work
HAR: Execute Plans.md tasks from single task to full parallel team run. Trigger: implement, execute, do everything, breezing, team run, parallel. Do NOT load for: planning, review, release, setup.
harness-sync
HAR: Sync Plans.md with implementation. Drift detect, marker update, retrospective. Trigger: sync-status, where am I, check progress. --snapshot for snapshots. Do NOT load for: planning, implementation, review, release.