x-internal-summarize-epic
Generates ai/memory/epic-XXXX-summary.md from a completed epic's artifacts using structured header parsing
- License 许可
- MIT
- 最近更新
- 2026-10-27
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- x-internal-summarize-epic
- model
- haiku
- visibility
- internal
- description
- Generates ai/memory/epic-XXXX-summary.md from a completed epic's artifacts using structured header parsing
- allowed-tools
- [ "Read", "Write", "Bash", "Grep", "Glob" ]
- context-budget
- light
- user-invocable
- false
- requires-capabilities
- [ "governance.ai-memory" ]
03 SKILL.md 正文
🔒 INTERNAL SKILL — Invoked only by other skills via the Skill tool. Not user-invocable.
x-internal-summarize-epic
Deterministic memory summary generator for completed epics. Parses epic markdown with structured
header extraction (not free-form regex), composes _TEMPLATE-EPIC-MEMORY-SUMMARY.md, and writes
ai/memory/epic-XXXX-summary.md + updates ai/memory/_index.yaml.
Determinism contract: Same inputs MUST produce bytewise-identical output across runs. Use explicit extraction rules; never introduce creative variance.
Triggers
Invoked by x-implement-epic Phase 5 (Rule 33):
Skill(skill: "x-internal-summarize-epic", args: "--epic-id EPIC-XXXX")
Parameters
| Flag | Type | Default | Description |
|---|---|---|---|
--epic-id |
EPIC-\d{4} |
required | Epic identifier |
--out-dir |
path | ai/memory/ |
Output directory override (tests) |
--dry-run |
bool | false | Print content without writing files or updating index |
--allow-legacy-fallback |
bool | false | For retro-seed (story-0075-0006) only — generates placeholder when v2 Decision sections absent |
Exit Codes
| Exit | Code | Condition |
|---|---|---|
| 0 | OK | Summary written and index updated |
| 1 | EPIC_NOT_FOUND | ai/epics/epic-XXXX-*/ absent |
| 2 | SCHEMA_VIOLATION | Generated frontmatter fails frontmatter-3.0.json |
| 3 | MEMORY_SUMMARY_TOO_LONG | Body exceeds 200 lines after composition |
| 4 | EXTRACTION_FAILED | Section 6 (Decision Rationale) absent on v2 epic and --allow-legacy-fallback not set |
| 5 | INDEX_LOCK_TIMEOUT | Failed to acquire flock on ai/memory/_index.yaml within 5s |
| 6 | TEMPLATE_VERSION_MISMATCH | summary-version in template changed; mass-regeneration required |
| 7 | MANUAL_REFINEMENT_PRESENT | Summary file contains <!-- manually-refined: --> marker; abort to preserve human override |
Execution Protocol
Step 1 — Locate epic
find ai/epics -maxdepth 1 -type d -name "epic-XXXX-*" | head -1
Exit 1 EPIC_NOT_FOUND when no directory matches.
Step 2 — Check for manual refinement
Read ai/memory/epic-XXXX-summary.md if it exists. If it contains <!-- manually-refined:, exit 7
MANUAL_REFINEMENT_PRESENT.
Step 3 — Extract sections (structured parser — deterministic)
Read ai/epics/epic-XXXX-*/epic-XXXX.md. Apply extraction rules below in order:
| Target section | Source | Extraction rule |
|---|---|---|
## Why this epic existed |
## 1. Visão & Problema (v2) or ## Contexto (v1) |
First paragraph only; trim to 5 lines max |
## Hypothesis tested |
## 3. Hipótese & OKRs (v2) |
Extract If...then...because line; append outcome: pending if no completion report |
## Decisions taken (with why) |
## 8. Decision Rationale or ## 6.* sub-sections |
Lines starting with **Decisão:**, **Motivo:**, **Consequência:**; if absent and --allow-legacy-fallback → placeholder |
## Alternatives rejected (with why) |
Same source | Lines starting with **Alternativa descartada:** |
## Reusable patterns produced |
Same source + keyword scan | Lines matching `/padrão |
## Anti-patterns observed |
Same source + keyword scan | Lines matching `/anti-padrão |
## Links |
Deterministic filesystem + ADR frontmatter | Epic path, adrs-referenced, story list, reports/ dir |
Step 4 — Assemble frontmatter
Extract deterministically:
tags: normalize headers to taxonomy IDs fromtags-catalog.mdcapabilities-affected: greprequires-capabilities:in story filesrules-affected: grepRule \d+in epic markdownadrs-referenced: grepADR-\d{4}in epic markdownpatterns-introduced/antipatterns-rejected: mirror Step 3 extractiondependencies-of/dependencies-for: grepDepende de:/Blocks:
Step 5 — Validate and write
- Count lines in composed summary. If > 200 → exit 3
MEMORY_SUMMARY_TOO_LONG. - Validate frontmatter against schema. If fails → exit 2
SCHEMA_VIOLATION. - If
--dry-run: print to stdout, exit 0. - Write
{out-dir}/epic-XXXX-summary.md. - Acquire flock on
{out-dir}/_index.yaml(5s timeout → exit 5). Update entry:- If entry exists: preserve
indexableandarchivedflags; updatelast-updated. - If new entry: add with
indexable: true,archived: false.
- If entry exists: preserve
- Release flock. Exit 0.
Integration Notes
- Invoked by
x-implement-epicPhase 5 (Rule 33 — MANDATORY TOOL CALL). --allow-legacy-fallbackis forx-internal-summarize-epiccalled from retro-seed (story-0075-0006); normal Phase 5 invocations MUST NOT pass this flag.- Idempotent: re-execution regenerates the summary completely (no append).
- Uses
_TEMPLATE-EPIC-MEMORY-SUMMARY.mdfrom.claude/templates/(present whengovernance.ai-memoryactive).
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.