x-internal-write-story-report
Generates the final consolidated story-completion report by reading ai/epics/epic-XXXX/execution-state.json, collecting per-task status and commitSha, PR metadata (prNumber, prState), coverage delta, and review findings, then rendering the output via x-internal-write-report with _TEMPLATE-STORY-COMPLETION-REPORT.md to the caller-specified --output path. Eighth skill in the x-internal-* convention and the fifth under internal/plan/ (after x-internal-load-story-context, x-internal-build-story-plan, x-internal-verify-story, and x-internal-resume-story). Read-only against state; writes only to --output via x-internal-write-report.
- License 许可
- MIT
- 最近更新
- 2026-10-27
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- x-internal-write-story-report
- category
- internal-plan
- visibility
- internal
- description
- Generates the final consolidated story-completion report by reading ai/epics/epic-XXXX/execution-state.json, collecting per-task status and commitSha, PR metadata (prNumber, prState), coverage delta, and review findings, then rendering the output via x-internal-write-report with _TEMPLATE-STORY-COMPLETION-REPORT.md to the caller-specified --output path. Eighth skill in the x-internal-* convention and the fifth under internal/plan/ (after x-internal-load-story-context, x-internal-build-story-plan, x-internal-verify-story, and x-internal-resume-story). Read-only against state; writes only to --output via x-internal-write-report.
- allowed-tools
- Bash, Skill
- argument-hint
- --story-id <story-XXXX-YYYY> --epic-id <XXXX> --output <path>
- context-budget
- heavy
- user-invocable
- false
- requires-capabilities
- []
02 资源文件 1
- 参考文档references/full-protocol.md10.2 KB
03 SKILL.md 正文
Global Output Policy
- Language: English ONLY.
- Tone: Technical, Direct, and Concise.
- Efficiency: Remove all conversational fillers and greetings to save tokens.
🔒 INTERNAL SKILL Esta skill é invocada apenas por outras skills (orquestradores). NÃO é destinada a invocação direta pelo usuário. Caller principal: x-implement-story (Phase 3 carve-out — final report). Oitava skill da convenção
x-internal-*(após x-internal-update-status pilot 0049-0005, x-internal-write-report 0049-0006, x-internal-normalize-args 0049-0007, x-internal-load-story-context 0049-0011, x-internal-build-story-plan 0049-0012, x-internal-verify-story 0049-0014, e x-internal-resume-story 0049-0013). Quinta skill eminternal/plan/: o subdirplan/agrupa orquestração de planejamento e verificação da story; esta skill fecha a quíntuplaload → build → verify → resume → reportcom o report final consolidado. Difere deinternal/ops/, cujas sibling skills mutam estado compartilhado (execution-state, append-markers); esta skill é single-writer para o seu próprio--outpute delega o render ax-internal-write-report.
Skill: x-internal-write-story-report
Purpose
Carve out the "final story report" block that x-implement-story
currently inlines at the end of Phase 3 into a single,
single-responsibility skill. The orchestrator passes three flags
(--story-id, --epic-id, --output) and consumes a compact
{reportPath, summary} envelope; the skill handles data collection,
template resolution, and rendering delegation.
Responsibilities (single):
- Locate and read
ai/epics/epic-XXXX/execution-state.json; exit 1 (STATE_NOT_FOUND) when absent. - Extract the story node (
.stories.<story-id>) and its tasks map. - Compute the
summaryobject:tasksCount— total number of tasks under.stories.<id>.tasks.tasksDone— count of tasks whose status matches the DONE synonym set (see Step 2 below).commitsCount— count of distinctcommitShavalues observed across all tasks (null and empty strings excluded).prNumber— the story-level PR number if present; otherwisenull.prState— normalised PR state (MERGED,OPEN,CLOSED);nullwhen no PR exists.coverageLine/coverageBranch— percentages from.stories.<id>.verification.coveragewhen that block exists;nullwhen the verification gate has not run.
- Build a structured JSON data payload containing the scalar summary
plus per-task arrays (
tasks) and findings arrays (findings) sourced from.stories.<id>.reviewswhen available. - Resolve the template at
.claude/templates/_TEMPLATE-STORY-COMPLETION-REPORT.md; exit 2 (TEMPLATE_MISSING) when absent. - Invoke
Skill(skill: "x-internal-write-report", …)with the resolved template, the built payload, and the forwarded--outputpath. On render success, forwardoutputPathto the caller. - Emit the response envelope
{reportPath, summary}on stdout as a single JSON line.
Non-responsibilities (explicit):
- The skill does NOT mutate
execution-state.json; it is read-only against the state file (delegation tox-internal-update-status --read-onlyis not required because a single best-effort read is sufficient — downstreamx-internal-write-reportowns the atomic write of the report file). - The skill does NOT run tests, coverage, or review dispatch — those
values must already be present in the state file (written by
x-internal-verify-story,x-review-codebase, andx-review-prupstream). - The skill does NOT create branches, PRs, or mutate git state.
- The skill does NOT emit telemetry markers — the caller
(
x-implement-storyPhase 3) owns the phase boundary. - The skill does NOT implement its own render engine — it delegates
100% of placeholder substitution and
{{#each}}expansion tox-internal-write-report.
Convention Anchors (x-internal-*)
| Aspect | Value | Rationale |
|---|---|---|
| Path | internal/plan/x-internal-write-story-report/ |
internal/ prefix scopes visibility; plan/ co-locates with the other story-lifecycle carve-outs (x-internal-load-story-context, x-internal-build-story-plan, x-internal-verify-story, x-internal-resume-story) |
Frontmatter visibility |
internal |
Generator filters these from /help menu |
Frontmatter user-invocable |
false |
Declarative complement to visibility: internal |
| Body marker | > 🔒 **INTERNAL SKILL** block as first non-frontmatter content |
Visible to humans browsing the repo; no parsing required |
| Allowed tools | Bash, Skill |
Bash reads the state file and builds the JSON payload with jq; Skill dispatches x-internal-write-report for rendering. No direct Write / Edit surface |
| Naming | x-internal-{subject}-{action} |
Mirrors Rule 04 skill taxonomy; story-report = subject+action |
Audit rule: Rule 22 (Lifecycle Integrity) validates every skill under
internal/** satisfies all 6 anchors above. Violations fail
LifecycleIntegrityAuditTest.
Triggers
Bare-slash form is intentionally omitted — this skill is never
invoked by a human typing /x-internal-write-story-report in chat. All
invocations follow Rule 13 INLINE-SKILL pattern from a calling
orchestrator:
Skill(skill: "x-internal-write-story-report",
args: "--story-id story-0049-0001 --epic-id 0049 --output ai/epics/epic-XXXX/reports/story-XXXX-YYYY-report.md")
Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
--story-id <id> |
M | — | Story identifier (story-XXXX-YYYY canonical form; lowercase-normalised) |
--epic-id <id> |
M | — | 4-digit epic identifier (XXXX) — used to resolve ai/epics/epic-XXXX/ (zero-padded) |
--output <path> |
M | — | Target path for the rendered report; forwarded verbatim to x-internal-write-report --output |
All three flags support both --key value and --key=value forms.
Unknown or missing required flags exit with 64 (sysexits
EX_USAGE). --story-id is validated against
^story-[0-9]{4}-[0-9]{4}$; --epic-id is zero-padded to 4 digits
and validated against ^[0-9]{4}$.
Response Contract
On success the skill writes a single-line JSON object to stdout:
| Field | Type | Always Present | Description |
|---|---|---|---|
reportPath |
String |
yes | Absolute path of the written report (echoed from x-internal-write-report) |
summary |
Object |
yes | Compact summary used by the orchestrator for final logging (see sub-schema below) |
summary sub-schema
| Field | Type | Always Present | Description |
|---|---|---|---|
tasksCount |
Integer |
yes | Total tasks under .stories.<id>.tasks (0 when map is empty) |
tasksDone |
Integer |
yes | Subset of tasksCount in the DONE synonym set |
commitsCount |
Integer |
yes | Count of distinct non-empty commitSha values across tasks |
prNumber |
Integer | Null |
yes | Story-level PR number; null when no PR exists |
prState |
String | Null |
yes | MERGED, OPEN, or CLOSED; null when prNumber=null |
coverageLine |
Number | Null |
yes | Line-coverage percentage; null when verification has not run |
coverageBranch |
Number | Null |
yes | Branch-coverage percentage; null when verification has not run |
Example envelope (happy path)
{"reportPath":"/repo/ai/epics/epic-XXXX/reports/story-XXXX-YYYY-report.md","summary":{"tasksCount":5,"tasksDone":5,"commitsCount":5,"prNumber":42,"prState":"MERGED","coverageLine":96.4,"coverageBranch":92.1}}
Example envelope (story without PR — boundary)
{"reportPath":"/repo/ai/epics/epic-XXXX/reports/story-XXXX-YYYY-report.md","summary":{"tasksCount":4,"tasksDone":2,"commitsCount":2,"prNumber":null,"prState":null,"coverageLine":null,"coverageBranch":null}}
Exit Codes
| Code | Name | Condition | Message Format |
|---|---|---|---|
| 0 | SUCCESS | Report rendered and response envelope emitted | — |
| 1 | STATE_NOT_FOUND | ai/epics/epic-XXXX/execution-state.json missing or unreadable |
State missing: ai/epics/epic-XXXX/execution-state.json |
| 2 | TEMPLATE_MISSING | .claude/templates/_TEMPLATE-STORY-COMPLETION-REPORT.md absent |
Template missing: _TEMPLATE-STORY-COMPLETION-REPORT.md |
| 64 | EX_USAGE | Unknown or malformed flag | usage: --story-id <id> --epic-id <id> --output <path> |
| 127 | DEPENDENCY_MISSING | jq absent on PATH |
dependency missing: jq |
Render-time failures (e.g., UNRESOLVED_PLACEHOLDER) propagate the
x-internal-write-report exit code unchanged so the caller branches
on the original semantic. No envelope is emitted on any non-zero
exit.
Workflow
Step 1 — Argument parsing and path resolution
Parse the three flags via a tight while (($#)); case "$1" in … loop
to stay within the SkillSizeLinter 500-line budget without delegating
to x-internal-normalize-args (peer skill; same rationale as
x-internal-resume-story §1 of full-protocol).
epic_dir="ai/epics/epic-${epic_id}"
state_file="${epic_dir}/execution-state.json"
template_name="_TEMPLATE-STORY-COMPLETION-REPORT.md"
template_path="${CLAUDE_PROJECT_DIR}/.claude/templates/${template_name}"
Validate --output is not empty and does not contain .. above the
project root (Rule 06 path traversal guard). Reject unknown flags
with exit 64.
Step 2 — Read execution-state.json (single best-effort read)
if [[ ! -r "${state_file}" ]]; then
echo "State missing: ${state_file}" >&2
exit 1
fi
Parse the story node:
story_json=$(jq --arg sid "${story_id}" '.stories[$sid] // null' "${state_file}")
if [[ "${story_json}" == "null" ]]; then
echo "Story ${story_id} not present in state file" >&2
exit 1
fi
A story absent from the state file degrades to exit 1 (same as missing state) — consumers distinguish via the stderr message, not the exit code.
Step 3 — Compute summary fields
Tasks classification uses the same DONE synonym set as
x-internal-resume-story (see references §2):
DONE synonyms: DONE, MERGED, COMPLETE, Concluída, Concluida, Done, Merged
tasks_count=$(echo "${story_json}" | jq '.tasks // {} | length')
tasks_done=$(echo "${story_json}" | jq '
[ .tasks // {} | to_entries[] |
select(.value.status as $s |
["DONE","MERGED","COMPLETE","Concluída","Concluida","Done","Merged"] |
index($s)) ] | length')
commits_count=$(echo "${story_json}" | jq '
[ .tasks // {} | to_entries[] | .value.commitSha |
select(. != null and . != "") ] | unique | length')
pr_number=$(echo "${story_json}" | jq '.pr.number // null')
pr_state=$(echo "${story_json}" | jq '
if .pr.state then (.pr.state | ascii_upcase) else null end')
coverage_line=$(echo "${story_json}" | jq '.verification.coverage.line // null')
coverage_branch=$(echo "${story_json}" | jq '.verification.coverage.branch // null')
Step 4 — Build the render payload
Assemble the payload as a single jq -n expression so the
x-internal-write-report invocation receives canonical JSON:
data_json=$(jq -nc \
--arg storyId "${story_id}" \
--arg epicId "${epic_id}" \
--argjson tasksCount "${tasks_count}" \
--argjson tasksDone "${tasks_done}" \
--argjson commitsCount "${commits_count}" \
--argjson prNumber "${pr_number}" \
--argjson prState "$(jq -nc --arg s "${pr_state}" 'if $s=="null" or $s=="" then null else $s end')" \
--argjson coverageLine "$95" \
--argjson coverageBranch "$90" \
--argjson tasks "$(echo "${story_json}" | jq '[.tasks // {} | to_entries[] | {id: .key, status: .value.status, commitSha: (.value.commitSha // null)}]')" \
--argjson findings "$(echo "${story_json}" | jq '[.reviews.findings // [] | .[] | {severity: .severity, title: .title, file: (.file // null)}]')" \
'{storyId:$storyId, epicId:$epicId,
tasksCount:$tasksCount, tasksDone:$tasksDone,
commitsCount:$commitsCount,
prNumber:$prNumber, prState:$prState,
coverageLine:$coverageLine, coverageBranch:$coverageBranch,
tasks:$tasks, findings:$findings}')
Step 5 — Template existence gate
if [[ ! -r "${template_path}" ]]; then
echo "Template missing: ${template_name}" >&2
exit 2
fi
The pre-check is intentionally local (not delegated to
x-internal-write-report) so the orchestrator gets a distinct
TEMPLATE_MISSING exit code (2) rather than the renderer's
TEMPLATE_NOT_FOUND exit code (1 of that skill). This keeps the
two skills' exit-code spaces non-overlapping.
Step 6 — Delegate to x-internal-write-report
Skill(skill: "x-internal-write-report",
args: "--template _TEMPLATE-STORY-COMPLETION-REPORT.md \
--output ${output_path} \
--data ${data_json}")
The renderer handles all placeholder substitution and {{#each}}
loops. Its stdout is a single JSON line matching the
x-internal-write-report response contract
({outputPath, bytesWritten, placeholdersReplaced, entriesAppended});
this skill reads outputPath and discards the rest.
Step 7 — Emit response envelope
jq -nc \
--arg reportPath "${report_path}" \
--argjson summary "${summary_json}" \
'{reportPath:$reportPath, summary:$summary}'
Exit 0.
Examples
Example 1 — Happy path: fully-done story with merged PR
State snippet for story-0049-0001:
{
"stories": {
"story-0049-0001": {
"tasks": {
"TASK-0049-0001-001": {"status":"DONE","commitSha":"abc123"},
"TASK-0049-0001-002": {"status":"DONE","commitSha":"def456"},
"TASK-0049-0001-003": {"status":"DONE","commitSha":"ghi789"},
"TASK-0049-0001-004": {"status":"DONE","commitSha":"jkl012"},
"TASK-0049-0001-005": {"status":"DONE","commitSha":"mno345"}
},
"pr": {"number": 42, "state": "MERGED"},
"verification": {"coverage": {"line": 96.4, "branch": 92.1}},
"reviews": {"findings": []}
}
}
}
Invocation:
Skill(skill: "x-internal-write-story-report",
args: "--story-id story-0049-0001 --epic-id 0049 --output ai/epics/epic-XXXX/reports/story-XXXX-YYYY-report.md")
Envelope:
{"reportPath":"/repo/ai/epics/epic-XXXX/reports/story-XXXX-YYYY-report.md","summary":{"tasksCount":5,"tasksDone":5,"commitsCount":5,"prNumber":42,"prState":"MERGED","coverageLine":96.4,"coverageBranch":92.1}}
Exit: 0.
Example 2 — Story in progress (3 DONE, 2 PENDING)
The report is still generated; summary.tasksDone=3 while
summary.tasksCount=5. The rendered report includes a per-task
status table via the template's {{#each tasks}} block. Exit: 0.
Example 3 — Error: STATE_NOT_FOUND
Skill(skill: "x-internal-write-story-report",
args: "--story-id story-0049-0099 --epic-id 0099 --output /tmp/out.md")
Stderr:
State missing: ai/epics/epic-XXXX/execution-state.json
Exit: 1. No envelope emitted.
Example 4 — Error: TEMPLATE_MISSING
The state file exists but _TEMPLATE-STORY-COMPLETION-REPORT.md is
not present under .claude/templates/. Stderr:
Template missing: _TEMPLATE-STORY-COMPLETION-REPORT.md
Exit: 2.
Example 5 — Boundary: story without PR
State snippet: "pr" key is absent or null.
Envelope:
{"reportPath":"…","summary":{"tasksCount":4,"tasksDone":2,"commitsCount":2,"prNumber":null,"prState":null,"coverageLine":null,"coverageBranch":null}}
The rendered report omits the "Pull Request" section because the
template guards that block on {{prNumber}}. Exit: 0.
Outputs
| Artifact | Path | Description |
|---|---|---|
| Rendered report | <--output> |
Markdown file written via x-internal-write-report (atomic tmp+rename) |
| Response envelope | stdout | Single-line JSON (reportPath / summary) |
| Error diagnostic | stderr | Single line, non-empty only on exit ≠ 0 |
No file is created by this skill directly — every disk mutation is
delegated to x-internal-write-report, which provides the atomic
write contract.
Error Handling
| Scenario | Action |
|---|---|
| Missing required flag | Print usage: banner to stderr; exit 64 |
| Unknown flag | Print unknown flag <name>; usage:; exit 64 |
--output empty or traversal-unsafe |
Print output path unsafe; exit 64 |
jq absent on PATH |
Print dependency missing: jq; exit 127 |
execution-state.json missing |
Exit 1 (STATE_NOT_FOUND); no envelope |
| Story node absent from state | Exit 1; stderr distinguishes via message |
.tasks key absent |
Treat as empty map (tasksCount=0); exit 0 |
.pr key absent |
Emit prNumber=null, prState=null; exit 0 |
.verification.coverage absent |
Emit coverageLine=null, coverageBranch=null; exit 0 |
.reviews.findings absent |
Emit findings:[]; exit 0 |
| Template file absent | Exit 2 (TEMPLATE_MISSING); no envelope |
x-internal-write-report UNRESOLVED_PLACEHOLDER (exit 3) |
Propagate exit code 3 unchanged; stderr already populated by renderer |
x-internal-write-report WRITE_FAILED (exit 4) |
Propagate exit code 4 unchanged |
Performance Contract
- Target: < 500 ms end-to-end for a typical story (5–10 tasks) on a
laptop-class machine. Budget breakdown:
- Argument parse + state read: < 50 ms
- Summary JSON computation (jq): < 100 ms
- Payload assembly: < 50 ms
- Template resolution: < 10 ms
x-internal-write-reportinvocation: ~200 ms (its own contract)- Envelope emission: < 10 ms
- Memory bounded by state-file size + 2× payload size; the skill never loads the rendered report into memory.
- Idempotent under repeated invocations with identical state file
and
--outputpath (the renderer's atomic tmp+rename contract).
Testing
Story-0049-0015 ships the following acceptance test scenarios, mirroring Section 7 of the story file:
- Happy path — state with 5 DONE tasks and merged PR renders
the full report;
summary.tasksCount=5,summary.prState=MERGED. - Story in progress — 3 DONE + 2 PENDING renders a report with
per-task status;
summary.tasksDone=3,summary.tasksCount=5. - Error — STATE_NOT_FOUND — missing state file → exit 1, no envelope, stderr matches.
- Error — TEMPLATE_MISSING — template absent → exit 2, no envelope, stderr matches.
- Boundary — story sem PR —
.prabsent →prNumber=null,prState=null, rendered report omits the "Pull Request" section.
Goldens live under
src/test/resources/golden/internal/plan/x-internal-write-story-report/
and lock the SKILL.md rendering (per EPIC-0049 convention: generator
copies internal skills into .claude/skills/ flat layout but filters
them from /help — goldens validate the source, not the flattened
output).
Coverage requirement: ≥ 95% line / ≥ 90% branch across the invoking Bash codepaths (DoD Global).
Generator Filter Contract
The ia-dev-env generator MUST exclude skills with
visibility: internal from:
- The
.claude/README.mdskill-inventory table. - The
/helpmenu listing surfaced by Claude Code. - User-facing autocomplete in the chat input.
Internal skills are still copied into .claude/skills/ (flat layout)
so Skill(skill: "x-internal-write-story-report") invocations from other
skills resolve correctly. The invariant: user cannot see it;
orchestrators can invoke it.
Telemetry
Internal skills DO NOT emit phase.start / phase.end markers —
telemetry is produced by the invoking orchestrator (the phase
wrapping the orchestrator's own step — Phase 3 in this case — is
the correct aggregation boundary). Passive hooks still capture
tool.call for the underlying Bash invocations (jq) and the
nested Skill(x-internal-write-report) dispatch.
Reference: Rule 13 (Skill Invocation Protocol), Rule 22 (Lifecycle Integrity Audit), ADR-0010 (Interactive Gates Convention — exempts internal skills from the 3-option menu contract).
Integration Notes
| Skill | Relationship | Context |
|---|---|---|
x-implement-story |
caller (primary) | Phase 3 final-report carve-out: orchestrator passes --story-id --epic-id --output and consumes {reportPath, summary} |
x-internal-write-report |
downstream (delegated render) | Resolves {{KEY}} placeholders and {{#each tasks}} / {{#each findings}} loops against the payload built in Step 4 |
x-internal-update-status |
peer (read-only consumer) | Both read execution-state.json; this skill does NOT write to it |
x-internal-verify-story |
upstream producer | Writes .verification.coverage consumed in Step 3 |
x-internal-resume-story |
peer | Shares the DONE synonym set and task-classification logic; no runtime coupling |
x-review-codebase / x-review-pr |
upstream producers | Write .reviews.findings consumed in Step 4 |
x-reconcile-status |
downstream reader | May read the rendered report for epic-wide status reconciliation (never mutates concurrently) |
Downstream story that depends on this skill: story-0049-0019 (orchestrator consumes the envelope and deletes the inline Phase 3 final-report block).
Full workflow detail (argument-parser rejection matrix, summary
computation edge cases, render-payload schema contract with the
template, PR-state normalisation rules, performance profiling on
large stories, and the forward-compatibility policy for new
summary fields) lives in
references/full-protocol.md per
ADR-0011.
04 同仓库更多 Skills
x-parallel-eval
Detects and classifies file-collision risks between work units (tasks, stories, or epic phases) before parallel execution. Reads ## File Footprint blocks produced by x-task-plan / x-story-plan, applies the parallelism-heuristics knowledge pack (hard / regen / soft categories + hotspot overrides), and emits a collision matrix + serialization recommendation in Markdown (default) or JSON.
parallelism-heuristics
Canonical catalog of file-collision heuristics for parallel task, story, and epic execution. Defines the File Footprint block format, the three Conflict Categories (hard / regen / soft), a hotspot list of high-contention paths, and the degrade-with-warning policy. Consumed by x-task-plan, x-story-plan, x-epic-map, x-parallel-eval, and x-dev-*-implement.
x-watch-pr-ci
Polls a PR's CI checks and Copilot review status, blocking until checks complete or timeout. Returns one of 8 stable exit codes (SUCCESS=0, CI_PENDING_PROCEED=10, CI_FAILED=20, TIMEOUT=30, PR_ALREADY_MERGED=40, NO_CI_CONFIGURED=50, PR_CLOSED=60, PR_NOT_FOUND=70). Writes a versioned state-file for session resume.
x-validate-docs
Documentation freshness gate: validates 6 dimensions (readme, api-specs, grpc-proto, adr, skill-docs, system-architecture) against code changes in a PR. Stack-aware — only validates targets declared/auto-detected from ProjectConfig.documentation.targets. Returns exit non-zero on staleness; produces structured report.
x-update-system-architecture
Incrementally updates docs/architecture/system.md after an epic completes. Appends new entries to the Decision Log (§11) using x-internal-write-report --append (dedup by ## ID: marker) and surgically inserts component/integration changes into sections 1-10 via Edit. Idempotent: re-running with the same epic produces a byte-identical system.md.
x-update-architecture
Incrementally updates the service architecture document with changes from architecture plans. Adds new components, integrations, flows, and ADR references without rewriting existing content. Use after implementation to keep architecture documentation current.