x-internal-render-pr-body
Renders PR body Markdown from existing disk artifacts using one of two templates. --kind=implementation: reads review/verify/telemetry artifacts for a story and emits a structured implementation PR body. --kind=backlog: reads epic/map artifacts and emits a scaffolding PR body. Fail-open: absent artifacts produce human-readable placeholders, never audit-sentinel strings. Internal — invoked only by x-create-pr and x-create-feature.
- License 许可
- MIT
- 最近更新
- 2026-10-27
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- x-internal-render-pr-body
- model
- haiku
- category
- internal-pr
- visibility
- internal
- description
- Renders PR body Markdown from existing disk artifacts using one of two templates. --kind=implementation: reads review/verify/telemetry artifacts for a story and emits a structured implementation PR body. --kind=backlog: reads epic/map artifacts and emits a scaffolding PR body. Fail-open: absent artifacts produce human-readable placeholders, never audit-sentinel strings. Internal — invoked only by x-create-pr and x-create-feature.
- allowed-tools
- [ "Read", "Write", "Bash", "Skill" ]
- argument-hint
- --kind=implementation|backlog --story-id <story-XXXX-YYYY> --out <abs-path>
- context-budget
- light
- user-invocable
- false
- requires-capabilities
- []
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 — Invoked only by other skills via the Skill tool. Not user-invocable.
Skill: x-internal-render-pr-body
Purpose
Renders a PR body Markdown file from existing on-disk artifacts (review, verify, telemetry,
commits) and writes it to --out. Consumed by x-create-pr (kind=implementation) and
x-create-feature (kind=backlog). Fail-open: any missing source produces a human-readable
placeholder — never an audit-sentinel string recognized by audit-pr-evidence.sh.
Parameters
| Parameter | Required | Description |
|---|---|---|
--kind |
Yes | implementation or backlog |
--story-id |
When --kind=implementation |
Pattern story-XXXX-YYYY |
--epic-id |
When --kind=backlog |
Pattern epic-XXXX or EPIC-XXXX |
--out |
Yes | Absolute path for output Markdown file |
Exit Codes
| Exit | Code | Condition |
|---|---|---|
| 0 | OK | Body rendered and written successfully |
| 1 | INVALID_KIND | --kind absent or not implementation/backlog |
| 2 | OPERATIONAL_ERROR | template missing, write permission denied, path traversal detected |
| 3 | INVALID_SCOPE | --story-id absent for --kind=implementation; --epic-id absent for --kind=backlog |
Fail-Open Contract (RULE-004)
Every absent artifact produces a human-readable placeholder. Permitted placeholders:
(pending)— review artifacts not yet produced(not yet run)— verify gate not yet executed(no telemetry available)— events.ndjson absent or empty(none)— no tasks or commits found(no commits)— git log returns empty
Forbidden placeholder values (would trigger audit-pr-evidence.sh): story-XXXX-YYYY,
EPIC-XXXX, any pattern matching story-[0-9]{4}-[0-9]{4} as a verdict/decision value.
Triggers
This skill is internal — never typed by a user. Callers use Rule 13 INLINE-SKILL pattern:
Skill(skill: "x-internal-render-pr-body", args: "--kind=implementation --story-id story-XXXX-YYYY --out /abs/path/body.md")
Phase 0 — ARGS
<!-- TELEMETRY: phase.start -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-internal-render-pr-body Phase-0-Args
Parse and validate all arguments:
- Extract
--kind,--story-id,--epic-id,--outfrom argv. - Validate
--kind:case "$KIND" in implementation|backlog) ;; *) echo "INVALID_KIND: --kind is required (implementation|backlog)" >&2; exit 1 ;; esac - Validate scope argument:
if [[ "$KIND" == "implementation" && -z "$STORY_ID" ]]; then echo "INVALID_SCOPE: --story-id required for --kind=implementation" >&2; exit 3 fi if [[ "$KIND" == "backlog" && -z "$EPIC_ID" ]]; then echo "INVALID_SCOPE: --epic-id required for --kind=backlog" >&2; exit 3 fi - Validate
--story-idformat (kind=implementation):^story-[0-9]{4}-[0-9]{4}$. - Canonicalize
--outand verify it stays within${REPO_ROOT}(Rule 06 J6 — path traversal):REPO_ROOT=$(realpath "$CLAUDE_PROJECT_DIR") OUT_CANONICAL=$(realpath --canonicalize-missing "$OUT") if [[ "$OUT_CANONICAL" != "$REPO_ROOT"* ]]; then echo "OPERATIONAL_ERROR: --out path traversal detected: $OUT" >&2; exit 2 fi
<!-- TELEMETRY: phase.end -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-internal-render-pr-body Phase-0-Args ok
Phase 1 — GATHER
<!-- TELEMETRY: phase.start -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-internal-render-pr-body Phase-1-Gather
Read 7 data sources (kind=implementation only; backlog uses a different set — see Phase 1b in §Backlog extension). Build intermediate JSON envelope. Apply fail-open fallbacks.
Source 1 — Story markdown (Acceptance Criteria)
Locate story-{storyId}.md via PathResolver (searches ai/epics/*/, plans/epic-XXXX/).
Parse Gherkin Cenário: headings for acceptance criteria list.
Fallback: acceptanceCriteria: [] (empty list).
Source 2 — Specialist review verdict
Locate review-story-{storyId}.md under ai/epics/epic-XXXX-*/plans/ (v4) or plans/epic-XXXX/plans/ (v3).
Parse YAML-when-available: if head -1 <file> returns --- (YAML frontmatter), use
yq '.verdict' <file> (EPIC-0067 structured verdict). Otherwise, fallback regex:
grep -oP '(?<=\*\*Verdict:\s)(GO|NO-GO)' "$REVIEW_FILE" | head -1
Fallback if file absent or regex fails: specialistVerdict: "(pending)".
Source 3 — Tech-lead review decision
Locate techlead-review-story-{storyId}.md. Same YAML-when-available logic.
Fallback regex: grep -oP '(?<=\*\*Decision:\s)(GO|NO-GO)'.
Fallback: techleadDecision: "(pending)".
Source 4 — Verify envelope
Locate reports/verify-envelope-{storyId}.json. Parse via jq:
jq -r '.testsResult, .coverageLine, .coverageBranch' "$ENVELOPE"
Fallback per field: "(not yet run)".
Source 5 — Story completion report (task IDs)
Locate reports/story-completion-report-{storyId}.md. Parse task table rows:
grep -oP 'TASK-[0-9]{4}-[0-9]{4}-[0-9]{3}' "$REPORT" | sort -u | tr '\n' ', '
Fallback: taskIds: "(none)".
Source 6 — Commits
Run git log origin/develop..HEAD --oneline in REPO_ROOT. Capture stdout as commit list.
Fallback: commitsList: "(no commits)".
Source 7 — Orchestrator metadata
Capture:
orchSha:git rev-parse HEADinvocationSkill:x-implement-storyphase1Artifacts: list files matchingai/epics/*/plans/*-{storyId}.mdphase3Artifacts: list files matchingai/epics/*/reports/*-{storyId}.*
Escape all string values: replace | with \|, backticks with ```, newlines with space.
<!-- TELEMETRY: phase.end -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-internal-render-pr-body Phase-1-Gather ok
Phase 2 — TELEMETRY
<!-- TELEMETRY: phase.start -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-internal-render-pr-body Phase-2-Telemetry
Invoke scripts/telemetry-consolidate.sh (story-0066-0002) for the story scope:
TEL_JSON=$(scripts/telemetry-consolidate.sh --story="$STORY_ID" --format=json 2>/tmp/tel-err.txt)
TEL_EXIT=$?
TEL_EXIT=0: parse$TEL_JSONforactiveMs,elapsedMs,events,tasks[],topTools[]. Incorporate into envelope.TEL_EXIT=1(NO_TELEMETRY): setstoryActiveMin=(no telemetry available),storyElapsedMin=(no telemetry available),storyEventCount=(no telemetry available),tasks=[],topTools=[]. Emit WARNING to stderr.TEL_EXIT=2(OPERATIONAL_ERROR): same as exit 1 (warning + placeholder). Do NOT abort — telemetry is non-blocking per RULE-002.
Convert activeMs/elapsedMs to minutes: floor(ms / 60000).
<!-- TELEMETRY: phase.end -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-internal-render-pr-body Phase-2-Telemetry ok
Phase 3 — RENDER
<!-- TELEMETRY: phase.start -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-internal-render-pr-body Phase-3-Render
Select template based on --kind:
case "$KIND" in
implementation) TEMPLATE_NAME="_TEMPLATE-PR-IMPLEMENTATION.md" ;;
backlog) TEMPLATE_NAME="_TEMPLATE-PR-BACKLOG.md" ;;
esac
TEMPLATE_PATH="$CLAUDE_PROJECT_DIR/.claude/templates/$TEMPLATE_NAME"
If $TEMPLATE_PATH not found → emit OPERATIONAL_ERROR: template missing: $TEMPLATE_PATH and exit 2.
Invoke x-internal-write-report via Rule 13 Pattern 1 (INLINE-SKILL):
Skill(skill: "x-internal-write-report", args: "--template $TEMPLATE_PATH --data <json-envelope> --output $TEMP_OUT")
$TEMP_OUT is a temp file under ${REPO_ROOT}/.claude/tmp/pr-render-$STORY_ID.md.
<!-- TELEMETRY: phase.end -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-internal-render-pr-body Phase-3-Render ok
Phase 4 — WRITE
<!-- TELEMETRY: phase.start -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-internal-render-pr-body Phase-4-Write
Atomic write: move temp file to final --out path:
mv "$TEMP_OUT" "$OUT_CANONICAL" 2>/tmp/write-err.txt || {
echo "OPERATIONAL_ERROR: write permission denied or disk full: $(cat /tmp/write-err.txt)" >&2
exit 2
}
echo "$OUT_CANONICAL"
On success, emit the final path to stdout and exit 0.
<!-- TELEMETRY: phase.end -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-internal-render-pr-body Phase-4-Write ok
<!-- phase-no-gate: Phase 1.5 is a conditional sub-phase inside Phase 1 — no independent gate -->
Phase 1.5 — BACKLOG-GATHER (conditional on --kind=backlog)
Executed only when --kind=backlog. Reads backlog-specific sources to build the backlog
JSON envelope (distinct from the implementation envelope built in Phase 1).
Source 1 — Epic markdown
Locate epic-XXXX.md via PathResolver (searches ai/epics/epic-XXXX-*/, plans/epic-XXXX/).
Parse:
summary: first paragraph under## 1. Contexto & Escopoor## 1.1 Problemastories: table rows in## 9.2 Stories— extract Phase, Story ID, Layer, Bloqueada porsuccessMetrics: bullet items under## 5.2 Métricas Quantitativasor## Métricas de SucessooutOfScopeList: bullet items under section containing "Fora do escopo"
Escape all string values before JSON injection: replace | with \|, backticks with \`, newlines with space.
Fallbacks: summary: "(no summary)", stories: [], successMetrics: ["(no metrics declared)"], outOfScopeList: "(not documented)".
Source 2 — IMPLEMENTATION-MAP.md
Locate IMPLEMENTATION-MAP.md in the epic directory. Parse:
criticalPath: regex\*\*Critical path.*?:\*\*\s*(.+)orCaminho crítico.*?:\s*(.+)maxParallelism: regex\*\*Maximum parallelism.*?:\*\*\s*(\d+)orParalelismo máximo.*?:\s*(\d+)maxParallelPhase: regex\(Phase\s+([\w ]+)\)after maxParallelismtotalPhases: count of## Phase Nheaders
If IMPLEMENTATION-MAP.md absent:
echo "WARN: IMPLEMENTATION-MAP.md not found for ${EPIC_ID}" >&2
criticalPath="(map missing)"
maxParallelism=0
totalPhases=0
Source 3 — Spec markdown
Search for spec file:
SPEC=$(find "${REPO_ROOT}" -name "spec-*.md" -path "*/epic-XXXX-*/*" 2>/dev/null | head -1)
If found: specPath=$(realpath --relative-to="${REPO_ROOT}" "$SPEC"), specSha=$(git rev-parse "HEAD:${specPath}" 2>/dev/null || echo "(unknown)").
If not found: specPath="(spec not found)", specSha="(unknown)".
Source 4 — Coordinations with in-progress epics
for state_file in "${REPO_ROOT}"/ai/epics/*/execution-state.json; do
status=$(jq -r '.status // empty' "$state_file" 2>/dev/null)
if [[ "$status" == "Em Andamento" ]]; then
epic_id=$(jq -r '.epicId // empty' "$state_file" 2>/dev/null)
coordinations+="{\"epicId\":\"$epic_id\",\"status\":\"in_progress\"}"
fi
done
Fallback if none: coordinations: [{"epicId":"(none)","status":"none","hotFiles":"","risk":"none"}].
Error Handling
| Scenario | Action |
|---|---|
--kind absent/invalid |
Exit 1 INVALID_KIND |
--story-id absent for implementation |
Exit 3 INVALID_SCOPE |
--out path traversal |
Exit 2 OPERATIONAL_ERROR: path traversal |
| Template file missing | Exit 2 OPERATIONAL_ERROR: template missing |
| Write permission denied | Exit 2 OPERATIONAL_ERROR: write permission denied |
telemetry-consolidate.sh exit 1/2 |
WARNING + placeholder (continue) |
| Any artifact absent | Placeholder per RULE-004 (continue) |
Integration Notes
| Skill | Relationship |
|---|---|
x-create-pr |
Primary caller for --kind=implementation |
x-create-feature |
Caller for --kind=backlog (story-0066-0006) — RULE-007: backlog PR ## Orchestrator Evidence is reduced (no Story IDs; accrues in subsequent story PRs) |
x-internal-write-report |
Delegate for template rendering (Phase 3) |
scripts/telemetry-consolidate.sh |
Telemetry aggregator (Phase 2, story-0066-0002) |
_TEMPLATE-PR-IMPLEMENTATION.md |
Template consumed by Phase 3 (story-0066-0001) |
_TEMPLATE-PR-BACKLOG.md |
Template for backlog kind (story-0066-0001) |
Haiku eligibility (Rule 23 §criterion a): utility without design reasoning — reads files, formats data, writes output. No architectural choices. Upgrade to sonnet/opus must be justified in this section with concrete rationale.
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.