AGENT SKILL

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:

  1. Extract --kind, --story-id, --epic-id, --out from argv.
  2. Validate --kind:
    case "$KIND" in
      implementation|backlog) ;;
      *) echo "INVALID_KIND: --kind is required (implementation|backlog)" >&2; exit 1 ;;
    esac
    
  3. 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
    
  4. Validate --story-id format (kind=implementation): ^story-[0-9]{4}-[0-9]{4}$.
  5. Canonicalize --out and 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 HEAD
  • invocationSkill: x-implement-story
  • phase1Artifacts: list files matching ai/epics/*/plans/*-{storyId}.md
  • phase3Artifacts: list files matching ai/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_JSON for activeMs, elapsedMs, events, tasks[], topTools[]. Incorporate into envelope.
  • TEL_EXIT=1 (NO_TELEMETRY): set storyActiveMin=(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 & Escopo or ## 1.1 Problema
  • stories: table rows in ## 9.2 Stories — extract Phase, Story ID, Layer, Bloqueada por
  • successMetrics: bullet items under ## 5.2 Métricas Quantitativas or ## Métricas de Sucesso
  • outOfScopeList: 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*(.+) or Caminho crítico.*?:\s*(.+)
  • maxParallelism: regex \*\*Maximum parallelism.*?:\*\*\s*(\d+) or Paralelismo máximo.*?:\s*(\d+)
  • maxParallelPhase: regex \(Phase\s+([\w ]+)\) after maxParallelism
  • totalPhases: count of ## Phase N headers

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

review-bench
review-bench/edercnj_ia-dev-environment

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.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

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.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

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.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

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.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

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.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

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.

★ 0