AGENT SKILL

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]
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-epic in parallel.
  • x-epic-map Step 8.5 (story-0041-0005), which invokes this skill as a gate.
  • x-dev-*-implement future 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

  1. Parse the CLI arguments and classify scope (epic / story / task).
  2. For --scope=epic: enumerate story-XXXX-YYYY.md files under the epic directory, extract the ## File Footprint block and the Blocked By column, and derive phases topologically.
  3. For --scope=story|task: read the two artefacts directly.
  4. Any artefact lacking a ## File Footprint block 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 in read: → safe to run in parallel (ignored unless --include-soft is passed).

Hotspot paths from the KP catalogue (RULE-004) force a hard classification regardless of the nominal write / regen sets.

Phase 3 — Emit report

  1. 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
    
  2. Write to stdout by default, or to --out when supplied.

  3. 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 Footprint block only (RULE-001).
  • Hard-failing when a footprint is missing — degrade with warning (RULE-005).
  • Mutating any file other than the --out target.

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