x-evaluate-parallelism
Detects and classifies file-collision risks between work units (tasks, stories, or epic phases) before parallel execution. Reads ## File Footprint blocks produced by x-plan-task / x-plan-story, applies the parallelism-heuristics knowledge pack (hard / regen / soft categories + hotspot overrides), and emits a collision matrix + serialization recommendation in Markdown (default) or JSON.
- License 许可
- MIT
- 最近更新
- 2026-10-27
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- x-evaluate-parallelism
- description
- Detects and classifies file-collision risks between work units (tasks, stories, or epic phases) before parallel execution. Reads ## File Footprint blocks produced by x-plan-task / x-plan-story, applies the parallelism-heuristics knowledge pack (hard / regen / soft categories + hotspot overrides), and emits a collision matrix + serialization recommendation in Markdown (default) or JSON.
- allowed-tools
- [ "Bash", "Read", "Skill" ]
- argument-hint
- --scope=epic|story|task [--epic PATH] [--a ID --b ID] [--out PATH] [--format markdown|json]
- context-budget
- light
- user-invocable
- true
- requires-capabilities
- []
03 SKILL.md 正文
Skill: x-evaluate-parallelism
Purpose
Evaluate the merge-conflict risk of running two or more work units in parallel,
using the canonical file-collision heuristics catalogued in the
parallelism-heuristics knowledge pack. The skill is intentionally cascading:
it consumes the structured ## File Footprint blocks already emitted by
x-plan-task (Phase 4.5) and x-plan-story (Phase 6), so the output is
deterministic and independent of prose parsing (RULE-008).
The primary consumers are:
- Operators validating an epic before dispatching
x-implement-epicin parallel. x-epic-mapStep 8.5 (story-0041-0005), which invokes this skill as a gate.x-dev-*-implementfuture gates (story-0041-0006).
When to Use
- Before approving an Implementation Map to confirm that declared parallel phases are actually conflict-free.
- When comparing two stories or two tasks in isolation to decide whether they can be coalesced into the same wave.
- As a read-only audit after the fact ("did we ship these in parallel safely?").
CLI Arguments
| Flag | Required | Description |
|---|---|---|
--scope |
Yes | epic, story, or task |
--epic |
If --scope=epic |
Path to the epic directory (e.g., ai/epics/epic-XXXX) |
--a / --b |
If --scope=story|task |
IDs of the pair to compare |
--out |
No | Output file path (writes to stdout by default) |
--format |
No | markdown (default) or json |
--map |
No | Implementation map path; when supplied its declared phases override the topological derivation |
--include-soft |
No | Include SOFT (read-only) overlaps in the output |
Exit Codes
| Code | Meaning |
|---|---|
| 0 | No conflicts detected |
| 1 | Warnings only (e.g., legacy footprints missing) |
| 2 | Hard or regen conflicts detected |
Workflow
Phase 1 — Resolve scope and load footprints
- Parse the CLI arguments and classify scope (
epic/story/task). - For
--scope=epic: enumeratestory-XXXX-YYYY.mdfiles under the epic directory, extract the## File Footprintblock and theBlocked Bycolumn, and derive phases topologically. - For
--scope=story|task: read the two artefacts directly. - Any artefact lacking a
## File Footprintblock is reported as a warning (RULE-005 — Degrade with Warning) and flagged as non-parallel.
Phase 2 — Classify collisions
For every pair within the same phase, apply the rules in the
parallelism-heuristics KP (RULE-003):
hard— both units write the same path → must be serialized.regen— one writes, the other regenerates (or both regenerate) the same path → must be serialized.soft— overlap only inread:→ safe to run in parallel (ignored unless--include-softis passed).
Hotspot paths from the KP catalogue (RULE-004) force a hard classification
regardless of the nominal write / regen sets.
Phase 3 — Emit report
-
Render the report in Markdown (default) or JSON (
--format=json). The Markdown shape is:# Parallelism Evaluation — EPIC-XXXX **Scope:** epic | **Items analyzed:** N | **Conflicts:** H hard, R regen, S soft ## Collision Matrix | A | B | Category | Shared paths | | :--- | :--- | :--- | :--- | ... ## Recommended Serialization Groups - **Group N (serialize):** story-... → story-... - **Group N (parallel):** story-..., story-... ## Hotspot Touches - `path` touched by: story-X, story-Y -
Write to stdout by default, or to
--outwhen supplied. -
Return the exit code derived from
hardCount + regenCount + warnings(see table above).
Invocation Examples
/x-evaluate-parallelism --scope=epic --epic ai/epics/epic-XXXX
/x-evaluate-parallelism --scope=epic --epic ai/epics/epic-XXXX --out reports/parallelism.md
/x-evaluate-parallelism --scope=story --a story-0041-0002 --b story-0041-0003
/x-evaluate-parallelism --scope=task --a TASK-0041-0002-001 --b TASK-0041-0003-001
The skill shells out to the project CLI (parallel-eval subcommand backed by
dev.iadev.parallelism.cli.ParallelEvalCli). It is side-effect-free except
when --out is supplied.
Knowledge Pack Reference
parallelism-heuristics— canonical catalogue of the File Footprint block format, conflict categories (hard / regen / soft), hotspot list, and degrade-with-warning policy. Read before modifying collision rules.
Integration Notes
| Consumer | Relationship | Context |
|---|---|---|
x-epic-map |
Invokes (Step 8.5) | Parallel-dispatch gate before an epic plan is approved |
x-plan-story |
Produces input | Emits the ## File Footprint blocks read here |
x-plan-task |
Produces input | Emits the per-task footprints used in --scope=task |
x-dev-*-implement |
Invokes (future, EPIC-0041 §5+) | Pre-dispatch safety check before parallel worktrees |
Determinism (RULE-008)
Running the skill twice with the same inputs MUST produce byte-identical outputs. Implementation rules that enforce this:
- All sets are stored as
TreeSet(alphabetical iteration). - Collisions are sorted by
(a, b)ascending before rendering. - Phase derivation is lexicographic when ties appear in the topological ordering.
Forbidden
- Inferring footprints from prose — the skill MUST use the structured
## File Footprintblock only (RULE-001). - Hard-failing when a footprint is missing — degrade with warning (RULE-005).
- Mutating any file other than the
--outtarget.
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.