[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M754RVCHHC82GV1V3HFXXKSD":3,"skill-same:01M754RVCHHC82GV1V3HFXXKSD":58},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":29,"commitSha":30,"skillDirectory":31,"forksCount":32,"repositoryHtmlUrl":33,"repositoryHomepageUrl":6,"ownerHtmlUrl":34,"ownerBlogUrl":35,"ownerDescription":36,"updatedAt":37,"install":38,"resources":51},"01M754RVCHHC82GV1V3HFXXKSD","x-internal-map-epic",null,"Generate Implementation Map from Epic and Stories: dependency matrix, phase computation, critical path, ASCII diagrams, Mermaid graphs, strategic observations. Invoked only by x-create-feature (Phase 4).","review-bench\u002Federcnj_ia-dev-environment","review-bench","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F286778065?v=4","01M7517F9NTEPDZDAXJBR30FWT","ReviewBench","01M7517FAC9F4P7TGWCNJ8VYVW",0,"MIT","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring-fintech-pci\u002F.claude\u002Fskills\u002Fx-internal-map-epic\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: x-internal-map-epic\ndescription: \"Generate Implementation Map from Epic and Stories: dependency matrix, phase computation, critical path, ASCII diagrams, Mermaid graphs, strategic observations. Invoked only by x-create-feature (Phase 4).\"\nvisibility: internal\nuser-invocable: false\nmodel: sonnet\nallowed-tools: Read, Write, Edit, Bash, Grep, Glob, Skill\nrequires-capabilities: []\ncontext-budget: medium\n---\n\n> 🔒 **INTERNAL SKILL** — Invoked only by other skills via the Skill tool. Not user-invocable.\n\n## Output Policy\n\n- **Language**: Portuguese (pt-BR) for all content. English for technical terms (cache, timeout, handler, endpoint) and code identifiers.\n- **Tone**: Technical, Direct, and Concise.\n- **Efficiency**: Remove all conversational fillers and greetings to save tokens.\n\n# Skill: Implementation Map Generator\n\n## Purpose\n\nTake the Epic and all Story files and compute the implementation plan: which stories can run in parallel, what the minimum implementation time is, where the bottlenecks are, and how to optimize team allocation. Produce ASCII phase diagrams, Mermaid dependency graphs, and strategic observations for sprint planning.\n\n## Triggers\n\n- `\u002Fx-epic-map \u003Cepic_file>` — generate implementation map from epic and stories\n- User asks to create an implementation map, generate a dependency graph, or compute implementation phases\n- User mentions sequencing stories, finding bottlenecks, computing parallel work streams, or building a roadmap from an epic\n\n## Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `\u003CEPIC_FILE>` | Path | Yes | — | Path to the Epic file (with story index and dependency declarations) |\n| `--dry-run` | Boolean | No | false | When true, the Implementation Map is written to disk but Steps P4 \u002F P5 (planning-commit \u002F push) become no-ops with a `\"dry-run, skipping commit\"` warning (EPIC-0049 \u002F RULE-007). |\n\n## Prerequisites\n\nRead the following files before starting:\n\n**Template (output structure):**\n- `.claude\u002Ftemplates\u002F_TEMPLATE-IMPLEMENTATION-MAP.md` — The exact structure to follow\n\n**Required inputs:**\n- The Epic file (with story index and dependency declarations)\n- All Story files (with their Blocked By \u002F Blocks tables)\n\n## Workflow\n\n### Step P1 — Detect Worktree Context (EPIC-0049 \u002F RULE-001)\n\n\u003C!-- TELEMETRY: phase.start -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh start x-epic-map Phase-P1-Worktree-Detect`\n\nInvoke `x-manage-worktrees` in detect-context mode so downstream steps know whether the current checkout is already inside an epic worktree. Result is advisory only — `x-internal-ensure-epic-branch` (Step P2) owns the authoritative branch decision.\n\n    Skill(skill: \"x-manage-worktrees\", args: \"detect-context\")\n\nFail-open (RULE-006): any detect-context failure is logged and Step P2 proceeds.\n\n\u003C!-- TELEMETRY: phase.end -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh end x-epic-map Phase-P1-Worktree-Detect ok`\n\n### Step P2 — Ensure `epic\u002F\u003CID>` Branch (EPIC-0049 \u002F RULE-001)\n\n\u003C!-- TELEMETRY: phase.start -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh start x-epic-map Phase-P2-Epic-Branch-Ensure`\n\nDerive the epic ID from the `\u003CEPIC_FILE>` path (`ai\u002Fepics\u002Fepic-\u003CXXXX>\u002Fepic-\u003CXXXX>.md`), then ensure the `epic\u002F\u003CXXXX>` branch exists locally AND on origin. The ensure skill is idempotent — a no-op when the caller is already on that branch.\n\n    Skill(skill: \"x-internal-ensure-epic-branch\", args: \"--epic-id \u003CXXXX>\")\n\nOn non-zero exit, abort with `EPIC_BRANCH_ENSURE_FAILED`.\n\n\u003C!-- TELEMETRY: phase.end -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh end x-epic-map Phase-P2-Epic-Branch-Ensure ok`\n\n### Step 1 — Build the Dependency Matrix\n\n\u003C!-- TELEMETRY: phase.start -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh start x-epic-map Phase-1-DAG-Build`\n\nRead every story's Section 1 (Dependencias) and the Epic's story index. Also read each\nstory's `**Chave Jira:**` field (if present). Build a complete matrix:\n\n| Story | Titulo | Chave Jira | Blocked By | Blocks | Status |\n| :--- | :--- | :--- | :--- | :--- | :--- |\n\nThe `Chave Jira` column is placed between `Titulo` and `Blocked By`. If a story does not\nhave a Jira key (field is `—` or `\u003CCHAVE-JIRA>`), set the column value to `—`.\n\n**Validation checks:**\n- Every story in the Epic's index must appear in the matrix\n- Dependencies must be symmetric: if A blocks B, then B must list A as blocker\n- No circular dependencies (A->B->C->A is invalid)\n- Root stories (no blockers) must exist — if every story has a blocker, something is wrong\n\nIf inconsistencies are found, fix them and note the corrections.\n\nAdd a `> **Nota:**` block for any implicit dependencies not declared in the stories but\nfunctionally required (e.g., \"story-0001-0009 provides configuration data that story-0001-0002 needs even\nthough story-0001-0002 does not explicitly declare it\").\n\n\u003C!-- TELEMETRY: phase.end -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh end x-epic-map Phase-1-DAG-Build ok`\n\n### Step 2 — Compute Phases\n\n\u003C!-- TELEMETRY: phase.start -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh start x-epic-map Phase-2-Phase-Computation`\n\nGroup stories into phases using the dependency DAG:\n\n1. **Phase 0**: All stories with no dependencies (roots)\n2. **Phase 1**: Stories whose dependencies are all in Phase 0\n3. **Phase N**: Stories whose dependencies are all in Phase 0..N-1\n\nWithin each phase, all stories can run in parallel.\n\nCreate the ASCII phase diagram using box-drawing characters. Follow the exact style from\nthe template — `+=+`, `|`, `+=+` for phase boxes, `+-+`, `|`, `+-+` for story boxes,\n`|-->`, `v` for arrows.\n\nEach story box shows: ID + short scope description (max ~20 chars).\nEach phase box shows: phase number + name + \"(paralelo)\" if multiple stories.\n\n\u003C!-- TELEMETRY: phase.end -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh end x-epic-map Phase-2-Phase-Computation ok`\n\n### Step 3 — Identify the Critical Path\n\n\u003C!-- TELEMETRY: phase.start -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh start x-epic-map Phase-3-Critical-Path`\n\nThe critical path is the longest chain of dependencies from any root to any leaf.\nCount phases, not individual stories.\n\nRender as a simple ASCII diagram:\n```\nstory-0001-0001 -+\n            +---> story-0001-0002 -> story-0001-0003 --+\nstory-0001-0009 -+                              +---> story-0001-0011\n                 story-0001-0002 -> story-0001-0010 --+\n   Fase 0           Fase 1       Fase 2            Fase 3\n```\n\nState: **N phases in the critical path, M stories in the longest chain**.\nExplain the impact: any delay in a critical path story directly delays the final delivery.\n\n\u003C!-- TELEMETRY: phase.end -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh end x-epic-map Phase-3-Critical-Path ok`\n\n### Step 4 — Generate the Mermaid Dependency Graph\n\n\u003C!-- TELEMETRY: phase.start -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh start x-epic-map Phase-4-Mermaid`\n\nCreate a full `graph TD` with all stories and their dependency edges.\n\n**Naming convention**: `SXXXX_YYYY[\"story-XXXX-YYYY\u003Cbr\u002F>Short Title\"]`\n\nIf Jira keys are available, include them in node labels:\n`SXXXX_YYYY[\"story-XXXX-YYYY (PROJ-123)\u003Cbr\u002F>Short Title\"]`\n\n**Phase coloring** (use these exact classDef values for consistency):\n```\nclassDef fase0 fill:#1a1a2e,stroke:#e94560,color:#fff\nclassDef fase1 fill:#16213e,stroke:#0f3460,color:#fff\nclassDef fase2 fill:#533483,stroke:#e94560,color:#fff\nclassDef fase3 fill:#e94560,stroke:#fff,color:#fff\nclassDef faseQE fill:#0d7377,stroke:#14ffec,color:#fff\nclassDef faseTD fill:#2d3436,stroke:#fdcb6e,color:#fff\nclassDef faseCR fill:#6c5ce7,stroke:#a29bfe,color:#fff\n```\n\nAssign classDef by phase. Group edges by phase transition (comment with `%% Fase N -> N+1`).\n\n\u003C!-- TELEMETRY: phase.end -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh end x-epic-map Phase-4-Mermaid ok`\n\n### Step 5 — Create the Phase Summary Table\n\n| Fase | Historias | Camada | Paralelismo | Pre-requisito |\n| :--- | :--- | :--- | :--- | :--- |\n| 0 | story-0001-0001, story-0001-0009 | Infra + API | 2 paralelas | — |\n\nInclude total count: **N historias em M fases**.\n\nAdd notes about transversal phases (QE, Tech Debt) that can execute independently of\nbusiness phases.\n\n### Step 6 — Detail Each Phase\n\nFor each phase, create a subsection with:\n\n**Table**: Story | Escopo Principal | Artefatos Chave\n\n**Entregas da Fase N** (bullet list of concrete deliverables — what exists after this\nphase that did not exist before).\n\nBe specific about artifacts: class names, table names, endpoints, configurations, test\ninfrastructure.\n\n### Step 7 — Write Strategic Observations\n\nThese are the highest-value part of the map. Analyze:\n\n**Gargalo Principal**: Which story blocks the most others? Investing extra time in\nit pays off. This is usually the Layer 1 core story.\n\n**Historias Folha (sem dependentes)**: Stories that do not block anything. They can absorb\ndelays without impacting the critical path. Good candidates for junior developers or\nparallel streams.\n\n**Otimizacao de Tempo**: Where is parallelism maximized? Which stories can start immediately?\nHow should teams be allocated across phases?\n\n**Dependencias Cruzadas**: Stories in later phases that depend on stories from different\nbranches of the dependency tree. Identify convergence points.\n\n**Marco de Validacao Arquitetural**: Which story should serve as the architectural\ncheckpoint before expanding scope? What does it validate (patterns, pipeline, integration)?\n\n### Step 8 — Task-Level Dependency Graph\n\nIf stories contain a **Section 8 (Sub-tarefas \u002F Tasks)** with formal task IDs\n(`TASK-XXXX-YYYY-NNN`), build a task-level dependency graph across all stories.\n\n#### 8A — Extract Cross-Story Task Dependencies\n\nFor each story, read the task list (Section 8) and their `depends on` declarations.\nIdentify cross-story task dependencies — tasks in one story that depend on tasks from\na different story. Build a table:\n\n| Task | Depends On | Story Source | Story Target | Type |\n| :--- | :--- | :--- | :--- | :--- |\n| TASK-XXXX-YYYY-NNN | TASK-XXXX-ZZZZ-MMM | story-XXXX-YYYY | story-XXXX-ZZZZ | data\u002Finterface\u002Fschema\u002Fconfig |\n\n**Type** indicates the nature of the dependency:\n- `data` — depends on data model or entity from another story\n- `interface` — depends on a port\u002Finterface defined in another story\n- `schema` — depends on a DB schema or migration from another story\n- `config` — depends on configuration or infrastructure from another story\n\n#### 8B — Validate RULE-012 (Cross-Story Consistency)\n\nFor every cross-story task dependency, validate that the corresponding story-level\ndependency exists:\n\n| Validation | Action |\n| :--- | :--- |\n| Cross-story task dep without story-level dep | **ERROR**: \"TASK-X depends on TASK-Y but story-A does not depend on story-B\" |\n| Cycle detected in task graph | **ERROR**: \"Cycle detected: TASK-A -> TASK-B -> TASK-C -> TASK-A\" |\n| Story-level dep without cross-story task dep | **WARNING**: \"story-A depends on story-B but no cross-story task dependencies found\" |\n\nIf an ERROR is detected, **abort** generation and report the inconsistency.\nIf only WARNINGs exist, proceed but include them in the output.\n\n#### 8C — Compute Merge Order via Topological Sort\n\nApply topological sort to the full task dependency graph (intra-story + cross-story):\n\n1. Build the directed graph of all tasks across all stories\n2. Detect cycles — if found, abort with cycle description\n3. Compute topological order (deterministic: break ties by task ID)\n4. Group tasks into execution phases (phase N = tasks whose dependencies are all in phases 0..N-1)\n5. Tasks in the same phase with no dependencies between them are **parallelizable**\n\nProduce a merge order table:\n\n| Order | Task ID | Story | Parallelizable With | Phase |\n| :--- | :--- | :--- | :--- | :--- |\n| 1 | TASK-XXXX-YYYY-NNN | story-XXXX-YYYY | TASK-XXXX-ZZZZ-MMM | 0 |\n\n#### 8D — Generate Mermaid Task Dependency Graph\n\nCreate a `graph LR` with tasks as nodes, colored by story:\n\n- **Subgraphs** group tasks by story, each with a distinct fill color\n- **Intra-story edges** use solid arrows (`-->`)\n- **Cross-story edges** use dashed arrows (`-.->`) with `|cross-story|` label\n- **Node labels** include task ID and short description\n\nUse these story colors (cycle through for more stories):\n```\nstyle story-1 fill:#e8f4fd\nstyle story-2 fill:#fde8e8\nstyle story-3 fill:#e8fde8\nstyle story-4 fill:#fdf8e8\nstyle story-5 fill:#f0e8fd\nstyle story-6 fill:#e8fdfa\n```\n\nExample:\n```mermaid\ngraph LR\n    subgraph story-XXXX-0001[\"Story 0001 (Foundation)\"]\n        style story-XXXX-0001 fill:#e8f4fd\n        T001[\"TASK-XXXX-0001-001\u003Cbr\u002F>Domain Model\"]\n        T002[\"TASK-XXXX-0001-002\u003Cbr\u002F>Port Interface\"]\n        T001 --> T002\n    end\n\n    subgraph story-XXXX-0002[\"Story 0002 (State)\"]\n        style story-XXXX-0002 fill:#fde8e8\n        T003[\"TASK-XXXX-0002-001\u003Cbr\u002F>State Record\"]\n        T004[\"TASK-XXXX-0002-002\u003Cbr\u002F>State Enum\"]\n        T003 --> T004\n    end\n\n    T002 -.->|cross-story| T003\n```\n\nIf stories do not contain formal task IDs, **skip this step entirely** and note:\n\"Task-level dependency graph skipped — stories do not contain formal task definitions (TASK-XXXX-YYYY-NNN).\"\n\n### Step 8.5 — Parallelism Conflict Analysis (EPIC-0041)\n\n\u003C!-- TELEMETRY: phase.start -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh start x-epic-map Phase-8-5-Parallelism-Eval`\n\nInvoke `\u002Fx-evaluate-parallelism --scope=epic` against the epic under analysis to detect file-level collision risks between stories that Step 2 placed in the same phase. The output feeds the \"## 8.5 Restrições de Paralelismo\" section of the map.\n\n**Fail-open behavior (RULE-005 \u002F RULE-006):** If the `x-evaluate-parallelism` skill is not available in the project (skill file missing under `.claude\u002Fskills\u002Fx-evaluate-parallelism\u002F` or `src\u002Fmain\u002Fresources\u002Ftargets\u002Fclaude\u002Fskills\u002Fcore\u002Fplan\u002Fx-evaluate-parallelism\u002F`) OR the invocation returns a non-zero exit code, DO NOT abort the map generation. Instead, emit section 8.5 with the following body:\n\n```markdown\n## 8.5 Restrições de Paralelismo\n\n> análise pulada — \u002Fx-evaluate-parallelism não disponível (RULE-006 fail-open)\n```\n\nand continue to Step 9. Log a WARNING with the reason (skill missing, exit code N, etc.) for operator diagnostics.\n\n**Happy-path output** (skill available and returned successfully):\n\n```markdown\n## 8.5 Restrições de Paralelismo\n\n> Análise gerada por \u002Fx-evaluate-parallelism em \u003Ctimestamp omitido para determinismo>.\n\n**Conflitos detectados:** \u003CH> hard, \u003CR> regen, \u003CS> soft\n\n### 8.5.1 Pares Serializados Dentro da Fase\n\n| Fase | A | B | Categoria | Motivo |\n| :--- | :--- | :--- | :--- | :--- |\n| \u003CPhase N> | \u003Cstory-A> | \u003Cstory-B> | \u003Chard|regen|soft> | \u003Cfile shared or regen collision> |\n\n### 8.5.2 Recomendação de Reagrupamento\n\n\u003CPara cada fase com conflitos, descrever a nova ordem após serialização forçada.>\n```\n\n**Determinism (RULE-008):** The section MUST be byte-identical across re-runs EXCEPT for the timestamp comment on the header line. The same input epic + story set MUST produce the same collision matrix ordering (sort pairs by Phase ASC → Story-A lexicographic → Story-B lexicographic).\n\n**Invocation shape:** Invoke via the Skill tool (Rule 13 — INLINE-SKILL pattern):\n\n    Skill(skill: \"x-evaluate-parallelism\", args: \"--scope=epic --epic \u003CEPIC_FILE>\")\n\n**Degenerate case:** If no conflicts are detected (`0 hard, 0 regen, 0 soft`), emit section 8.5 with \"Conflitos detectados: 0\" and omit subsections 8.5.1 \u002F 8.5.2.\n\n\u003C!-- TELEMETRY: phase.end -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh end x-epic-map Phase-8-5-Parallelism-Eval ok`\n\n### Step 9 — Save and Report\n\nSave as `IMPLEMENTATION-MAP.md` in the same directory as the Epic and Stories (inside `ai\u002Fepics\u002Fepic-XXXX\u002F`).\nReport: total stories, phases, critical path length, maximum parallelism, main bottleneck.\nIf task-level dependencies were computed, also report: total tasks, task phases, cross-story dependencies count.\n\n### Step P4 — Commit Implementation Map (EPIC-0049 \u002F RULE-007)\n\n\u003C!-- TELEMETRY: phase.start -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh start x-epic-map Phase-P4-Planning-Commit`\n\nIf `--dry-run` is set, log `\"dry-run, skipping commit\"` and skip this step entirely.\n\nOtherwise, delegate the commit to `x-commit-planning` so the refreshed `ai\u002Fepics\u002Fepic-XXXX\u002FIMPLEMENTATION-MAP.md` is versioned on the canonical `epic\u002F\u003CID>` branch without triggering the code pre-commit chain:\n\n    Skill(skill: \"x-commit-planning\",\n          args: \"--scope docs --epic-id \u003CXXXX> --paths ai\u002Fepics\u002Fepic-\u003CXXXX>\u002FIMPLEMENTATION-MAP.md --subject \\\"update implementation map\\\"\")\n\nIdempotency: when the map is byte-identical to the previously committed version, `x-commit-planning` returns `commitSha=null` and `noOp=true` (silent no-op). No additional diff check is required here.\n\nOn `COMMIT_FAILED` (exit 4), abort with the same error code.\n\n\u003C!-- TELEMETRY: phase.end -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh end x-epic-map Phase-P4-Planning-Commit ok`\n\n### Step P5 — Push to Origin (optional, EPIC-0049)\n\n\u003C!-- TELEMETRY: phase.start -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh start x-epic-map Phase-P5-Push`\n\nIf `--dry-run` is set, log `\"dry-run, skipping push\"` and skip.\n\nOtherwise, push the canonical epic branch so the updated map is observable on origin:\n\n    Skill(skill: \"x-push-branch\", args: \"--branch epic\u002F\u003CXXXX>\")\n\nOn push failure, log a WARNING and continue — the local commit is preserved; the operator re-runs manually. Do NOT abort.\n\n\u003C!-- TELEMETRY: phase.end -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh end x-epic-map Phase-P5-Push ok`\n\n## Error Handling\n\n| Scenario | Action |\n|----------|--------|\n| Template file missing | Abort with message: \"Template _TEMPLATE-IMPLEMENTATION-MAP.md not found\" |\n| Epic file missing or unparseable | Abort with message: \"Epic file not found or invalid format\" |\n| Story files missing | Abort with message: \"No story files found in epic directory\" |\n| Circular dependency detected | Warn with cycle details; break the cycle and proceed |\n| Asymmetric dependency (A blocks B but B does not list A) | Fix automatically and note the correction |\n| No root stories (all have blockers) | Warn: \"All stories have blockers — review for missing root stories\" |\n| Cross-story task dep without story-level dep (RULE-012) | Abort with error listing the inconsistent dependencies |\n| Cycle in task dependency graph | Abort with cycle path: \"Cycle detected: TASK-A -> TASK-B -> TASK-A\" |\n| Stories without formal task IDs | Skip Section 8 with note; proceed with story-level map only |\n| `\u002Fx-evaluate-parallelism` skill missing or exit code ≥ 1 (Step 8.5) | Fail-open: emit section 8.5 with \"análise pulada — \u002Fx-evaluate-parallelism não disponível\" (RULE-005 \u002F RULE-006); log WARNING; continue to Step 9 |\n| `x-internal-ensure-epic-branch` fails (Step P2) | Abort with `EPIC_BRANCH_ENSURE_FAILED`; canonical branch is required for versioning |\n| `x-commit-planning` exit 4 (Step P4) | Abort with `COMMIT_FAILED`; file written but not versioned |\n| `x-commit-planning` exit 0 + `noOp=true` (Step P4) | Silent no-op — re-execution idempotency confirmed; continue to Step P5 |\n| `x-push-branch` fails (Step P5) | WARN only; local commit preserved; operator re-runs manually |\n| `--dry-run` set | Steps P4 and P5 become no-ops with log line `\"dry-run, skipping commit\"` \u002F `\"dry-run, skipping push\"` |\n\n## Common Mistakes\n\n- **Phase computation error**: A story can only enter a phase when ALL its dependencies (not just some) are in earlier phases\n- **Missing convergence analysis**: When story-0001-0011 depends on story-0001-0003 AND story-0001-0010 from different branches, this creates a convergence point that deserves a callout\n- **Generic observations**: \"story-0001-0002 is important\" says nothing. \"story-0001-0002 blocks 6 stories and establishes the decision engine pattern that all Phase 2 handlers reuse — investing extra design time here prevents refactoring 6 handlers later\" is useful\n- **Inconsistent status**: If a story is marked Done in the matrix but Pending in the phase diagram, that is a bug\n- **Missing leaf analysis**: Leaf stories (no dependents) are strategically important because they can absorb schedule variance. Always identify them\n\n## Integration Notes\n\n| Skill | Relationship | Context |\n|-------|-------------|---------|\n| x-epic-create | reads | Reads the Epic file with story index and dependencies |\n| x-story-create | reads | Reads generated story files for dependency details |\n| x-epic-decompose | called-by | Orchestrator invokes x-epic-map in Phase D |\n| x-implement-epic | reads | Epic implementation reads the map for execution order |\n| x-manage-worktrees | calls (Step P1) | Detect-context (EPIC-0049 \u002F RULE-001) |\n| x-internal-ensure-epic-branch | calls (Step P2) | Ensure `epic\u002F\u003CID>` exists locally + origin (EPIC-0049 \u002F RULE-001) |\n| x-commit-planning | calls (Step P4) | Batch-commit implementation map without code pre-commit chain (EPIC-0049 \u002F RULE-007) |\n| x-push-branch | calls (Step P5) | Push canonical epic branch to origin (optional) |\n\n## Knowledge Pack References\n\n| Knowledge Pack | Usage |\n|----------------|-------|\n| story-planning | Phase computation, dependency DAG, critical path analysis |\n| parallelism-heuristics | Step 8.5 collision categories (hard\u002Fregen\u002Fsoft) consumed from `\u002Fx-evaluate-parallelism` output |\n\n## Planning Status Propagation (Rule 22 \u002F EPIC-0046)\n\n> V2-gated: only runs when the epic declares `planningSchemaVersion: \"2.0\"` in its `execution-state.json`. For v1 epics: skip silently (Rule 19).\n\n`x-epic-map` reads story files (it does NOT write to them) and emits\u002Frefreshes `ai\u002Fepics\u002Fepic-XXXX\u002FIMPLEMENTATION-MAP.md` with two lifecycle columns:\n\n- **Planejamento** — mirrors the current `**Status:**` of each story (values: `Pendente`, `Planejada`, `Em Andamento`, `Concluída`, `Falha`, `Bloqueada`).\n- **Status** — the execution lifecycle status (same six values; driven by `x-implement-story` \u002F `x-implement-epic` downstream).\n\nBoth columns are populated by reading the story files in situ via the CLI. `x-epic-map` never transitions any story — it is a read-only skill with respect to lifecycle status. The `{{PLANNING_STATUS}}` token in the implementation-map template is resolved at render-time by reading each story.\n\n**Steps (end of map generation, BEFORE the final commit):**\n\n1. Detect v2 via `execution-state.json`. If v1: leave legacy columns untouched (skip this block).\n2. For each story row being rendered into the map:\n   ```bash\n   STATUS=$(java -cp $CLAUDE_PROJECT_DIR\u002Fjava\u002Ftarget\u002Fclasses \\\n       dev.iadev.adapter.inbound.cli.StatusFieldParserCli \\\n       read ai\u002Fepics\u002Fepic-XXXX\u002Fstory-XXXX-YYYY.md)\n   ```\n   Use `$STATUS` to fill the `Planejamento` column for that row. Exit code 20 for any story → abort map generation (source-of-truth invariant RULE-046-01 must hold).\n3. The `Status` (execution) column is filled from `execution-state.json` (not from the story file) — the story's `**Status:**` line is authoritative for planning only in v2.\n4. Stage and commit the updated map:\n   ```bash\n   git add ai\u002Fepics\u002Fepic-XXXX\u002FIMPLEMENTATION-MAP.md\n   ```\n\n       Skill(skill: \"x-commit-changes\", args: \"docs(epic-XXXX): refresh implementation map with lifecycle columns\")\n\n**Fail-loud:** CLI exit 20 on any story aborts map generation (RULE-046-08). `x-epic-map` never calls `write` on a story — the skill only reads.\n","> 🔒 **INTERNAL SKILL** — Invoked only by other skills via the Skill tool. Not user-invocable.\n\n## Output Policy\n\n- **Language**: Portuguese (pt-BR) for all content. English for technical terms (cache, timeout, handler, endpoint) and code identifiers.\n- **Tone**: Technical, Direct, and Concise.\n- **Efficiency**: Remove all conversational fillers and greetings to save tokens.\n\n# Skill: Implementation Map Generator\n\n## Purpose\n\nTake the Epic and all Story files and compute the implementation plan: which stories can run in parallel, what the minimum implementation time is, where the bottlenecks are, and how to optimize team allocation. Produce ASCII phase diagrams, Mermaid dependency graphs, and strategic observations for sprint planning.\n\n## Triggers\n\n- `\u002Fx-epic-map \u003Cepic_file>` — generate implementation map from epic and stories\n- User asks to create an implementation map, generate a dependency graph, or compute implementation phases\n- User mentions sequencing stories, finding bottlenecks, computing parallel work streams, or building a roadmap from an epic\n\n## Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `\u003CEPIC_FILE>` | Path | Yes | — | Path to the Epic file (with story index and dependency declarations) |\n| `--dry-run` | Boolean | No | false | When true, the Implementation Map is written to disk but Steps P4 \u002F P5 (planning-commit \u002F push) become no-ops with a `\"dry-run, skipping commit\"` warning (EPIC-0049 \u002F RULE-007). |\n\n## Prerequisites\n\nRead the following files before starting:\n\n**Template (output structure):**\n- `.claude\u002Ftemplates\u002F_TEMPLATE-IMPLEMENTATION-MAP.md` — The exact structure to follow\n\n**Required inputs:**\n- The Epic file (with story index and dependency declarations)\n- All Story files (with their Blocked By \u002F Blocks tables)\n\n## Workflow\n\n### Step P1 — Detect Worktree Context (EPIC-0049 \u002F RULE-001)\n\n\u003C!-- TELEMETRY: phase.start -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh start x-epic-map Phase-P1-Worktree-Detect`\n\nInvoke `x-manage-worktrees` in detect-context mode so downstream steps know whether the current checkout is already inside an epic worktree. Result is advisory only — `x-internal-ensure-epic-branch` (Step P2) owns the authoritative branch decision.\n\n    Skill(skill: \"x-manage-worktrees\", args: \"detect-context\")\n\nFail-open (RULE-006): any detect-context failure is logged and Step P2 proceeds.\n\n\u003C!-- TELEMETRY: phase.end -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh end x-epic-map Phase-P1-Worktree-Detect ok`\n\n### Step P2 — Ensure `epic\u002F\u003CID>` Branch (EPIC-0049 \u002F RULE-001)\n\n\u003C!-- TELEMETRY: phase.start -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh start x-epic-map Phase-P2-Epic-Branch-Ensure`\n\nDerive the epic ID from the `\u003CEPIC_FILE>` path (`ai\u002Fepics\u002Fepic-\u003CXXXX>\u002Fepic-\u003CXXXX>.md`), then ensure the `epic\u002F\u003CXXXX>` branch exists locally AND on origin. The ensure skill is idempotent — a no-op when the caller is already on that branch.\n\n    Skill(skill: \"x-internal-ensure-epic-branch\", args: \"--epic-id \u003CXXXX>\")\n\nOn non-zero exit, abort with `EPIC_BRANCH_ENSURE_FAILED`.\n\n\u003C!-- TELEMETRY: phase.end -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh end x-epic-map Phase-P2-Epic-Branch-Ensure ok`\n\n### Step 1 — Build the Dependency Matrix\n\n\u003C!-- TELEMETRY: phase.start -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh start x-epic-map Phase-1-DAG-Build`\n\nRead every story's Section 1 (Dependencias) and the Epic's story index. Also read each\nstory's `**Chave Jira:**` field (if present). Build a complete matrix:\n\n| Story | Titulo | Chave Jira | Blocked By | Blocks | Status |\n| :--- | :--- | :--- | :--- | :--- | :--- |\n\nThe `Chave Jira` column is placed between `Titulo` and `Blocked By`. If a story does not\nhave a Jira key (field is `—` or `\u003CCHAVE-JIRA>`), set the column value to `—`.\n\n**Validation checks:**\n- Every story in the Epic's index must appear in the matrix\n- Dependencies must be symmetric: if A blocks B, then B must list A as blocker\n- No circular dependencies (A->B->C->A is invalid)\n- Root stories (no blockers) must exist — if every story has a blocker, something is wrong\n\nIf inconsistencies are found, fix them and note the corrections.\n\nAdd a `> **Nota:**` block for any implicit dependencies not declared in the stories but\nfunctionally required (e.g., \"story-0001-0009 provides configuration data that story-0001-0002 needs even\nthough story-0001-0002 does not explicitly declare it\").\n\n\u003C!-- TELEMETRY: phase.end -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh end x-epic-map Phase-1-DAG-Build ok`\n\n### Step 2 — Compute Phases\n\n\u003C!-- TELEMETRY: phase.start -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh start x-epic-map Phase-2-Phase-Computation`\n\nGroup stories into phases using the dependency DAG:\n\n1. **Phase 0**: All stories with no dependencies (roots)\n2. **Phase 1**: Stories whose dependencies are all in Phase 0\n3. **Phase N**: Stories whose dependencies are all in Phase 0..N-1\n\nWithin each phase, all stories can run in parallel.\n\nCreate the ASCII phase diagram using box-drawing characters. Follow the exact style from\nthe template — `+=+`, `|`, `+=+` for phase boxes, `+-+`, `|`, `+-+` for story boxes,\n`|-->`, `v` for arrows.\n\nEach story box shows: ID + short scope description (max ~20 chars).\nEach phase box shows: phase number + name + \"(paralelo)\" if multiple stories.\n\n\u003C!-- TELEMETRY: phase.end -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh end x-epic-map Phase-2-Phase-Computation ok`\n\n### Step 3 — Identify the Critical Path\n\n\u003C!-- TELEMETRY: phase.start -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh start x-epic-map Phase-3-Critical-Path`\n\nThe critical path is the longest chain of dependencies from any root to any leaf.\nCount phases, not individual stories.\n\nRender as a simple ASCII diagram:\n```\nstory-0001-0001 -+\n            +---> story-0001-0002 -> story-0001-0003 --+\nstory-0001-0009 -+                              +---> story-0001-0011\n                 story-0001-0002 -> story-0001-0010 --+\n   Fase 0           Fase 1       Fase 2            Fase 3\n```\n\nState: **N phases in the critical path, M stories in the longest chain**.\nExplain the impact: any delay in a critical path story directly delays the final delivery.\n\n\u003C!-- TELEMETRY: phase.end -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh end x-epic-map Phase-3-Critical-Path ok`\n\n### Step 4 — Generate the Mermaid Dependency Graph\n\n\u003C!-- TELEMETRY: phase.start -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh start x-epic-map Phase-4-Mermaid`\n\nCreate a full `graph TD` with all stories and their dependency edges.\n\n**Naming convention**: `SXXXX_YYYY[\"story-XXXX-YYYY\u003Cbr\u002F>Short Title\"]`\n\nIf Jira keys are available, include them in node labels:\n`SXXXX_YYYY[\"story-XXXX-YYYY (PROJ-123)\u003Cbr\u002F>Short Title\"]`\n\n**Phase coloring** (use these exact classDef values for consistency):\n```\nclassDef fase0 fill:#1a1a2e,stroke:#e94560,color:#fff\nclassDef fase1 fill:#16213e,stroke:#0f3460,color:#fff\nclassDef fase2 fill:#533483,stroke:#e94560,color:#fff\nclassDef fase3 fill:#e94560,stroke:#fff,color:#fff\nclassDef faseQE fill:#0d7377,stroke:#14ffec,color:#fff\nclassDef faseTD fill:#2d3436,stroke:#fdcb6e,color:#fff\nclassDef faseCR fill:#6c5ce7,stroke:#a29bfe,color:#fff\n```\n\nAssign classDef by phase. Group edges by phase transition (comment with `%% Fase N -> N+1`).\n\n\u003C!-- TELEMETRY: phase.end -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh end x-epic-map Phase-4-Mermaid ok`\n\n### Step 5 — Create the Phase Summary Table\n\n| Fase | Historias | Camada | Paralelismo | Pre-requisito |\n| :--- | :--- | :--- | :--- | :--- |\n| 0 | story-0001-0001, story-0001-0009 | Infra + API | 2 paralelas | — |\n\nInclude total count: **N historias em M fases**.\n\nAdd notes about transversal phases (QE, Tech Debt) that can execute independently of\nbusiness phases.\n\n### Step 6 — Detail Each Phase\n\nFor each phase, create a subsection with:\n\n**Table**: Story | Escopo Principal | Artefatos Chave\n\n**Entregas da Fase N** (bullet list of concrete deliverables — what exists after this\nphase that did not exist before).\n\nBe specific about artifacts: class names, table names, endpoints, configurations, test\ninfrastructure.\n\n### Step 7 — Write Strategic Observations\n\nThese are the highest-value part of the map. Analyze:\n\n**Gargalo Principal**: Which story blocks the most others? Investing extra time in\nit pays off. This is usually the Layer 1 core story.\n\n**Historias Folha (sem dependentes)**: Stories that do not block anything. They can absorb\ndelays without impacting the critical path. Good candidates for junior developers or\nparallel streams.\n\n**Otimizacao de Tempo**: Where is parallelism maximized? Which stories can start immediately?\nHow should teams be allocated across phases?\n\n**Dependencias Cruzadas**: Stories in later phases that depend on stories from different\nbranches of the dependency tree. Identify convergence points.\n\n**Marco de Validacao Arquitetural**: Which story should serve as the architectural\ncheckpoint before expanding scope? What does it validate (patterns, pipeline, integration)?\n\n### Step 8 — Task-Level Dependency Graph\n\nIf stories contain a **Section 8 (Sub-tarefas \u002F Tasks)** with formal task IDs\n(`TASK-XXXX-YYYY-NNN`), build a task-level dependency graph across all stories.\n\n#### 8A — Extract Cross-Story Task Dependencies\n\nFor each story, read the task list (Section 8) and their `depends on` declarations.\nIdentify cross-story task dependencies — tasks in one story that depend on tasks from\na different story. Build a table:\n\n| Task | Depends On | Story Source | Story Target | Type |\n| :--- | :--- | :--- | :--- | :--- |\n| TASK-XXXX-YYYY-NNN | TASK-XXXX-ZZZZ-MMM | story-XXXX-YYYY | story-XXXX-ZZZZ | data\u002Finterface\u002Fschema\u002Fconfig |\n\n**Type** indicates the nature of the dependency:\n- `data` — depends on data model or entity from another story\n- `interface` — depends on a port\u002Finterface defined in another story\n- `schema` — depends on a DB schema or migration from another story\n- `config` — depends on configuration or infrastructure from another story\n\n#### 8B — Validate RULE-012 (Cross-Story Consistency)\n\nFor every cross-story task dependency, validate that the corresponding story-level\ndependency exists:\n\n| Validation | Action |\n| :--- | :--- |\n| Cross-story task dep without story-level dep | **ERROR**: \"TASK-X depends on TASK-Y but story-A does not depend on story-B\" |\n| Cycle detected in task graph | **ERROR**: \"Cycle detected: TASK-A -> TASK-B -> TASK-C -> TASK-A\" |\n| Story-level dep without cross-story task dep | **WARNING**: \"story-A depends on story-B but no cross-story task dependencies found\" |\n\nIf an ERROR is detected, **abort** generation and report the inconsistency.\nIf only WARNINGs exist, proceed but include them in the output.\n\n#### 8C — Compute Merge Order via Topological Sort\n\nApply topological sort to the full task dependency graph (intra-story + cross-story):\n\n1. Build the directed graph of all tasks across all stories\n2. Detect cycles — if found, abort with cycle description\n3. Compute topological order (deterministic: break ties by task ID)\n4. Group tasks into execution phases (phase N = tasks whose dependencies are all in phases 0..N-1)\n5. Tasks in the same phase with no dependencies between them are **parallelizable**\n\nProduce a merge order table:\n\n| Order | Task ID | Story | Parallelizable With | Phase |\n| :--- | :--- | :--- | :--- | :--- |\n| 1 | TASK-XXXX-YYYY-NNN | story-XXXX-YYYY | TASK-XXXX-ZZZZ-MMM | 0 |\n\n#### 8D — Generate Mermaid Task Dependency Graph\n\nCreate a `graph LR` with tasks as nodes, colored by story:\n\n- **Subgraphs** group tasks by story, each with a distinct fill color\n- **Intra-story edges** use solid arrows (`-->`)\n- **Cross-story edges** use dashed arrows (`-.->`) with `|cross-story|` label\n- **Node labels** include task ID and short description\n\nUse these story colors (cycle through for more stories):\n```\nstyle story-1 fill:#e8f4fd\nstyle story-2 fill:#fde8e8\nstyle story-3 fill:#e8fde8\nstyle story-4 fill:#fdf8e8\nstyle story-5 fill:#f0e8fd\nstyle story-6 fill:#e8fdfa\n```\n\nExample:\n```mermaid\ngraph LR\n    subgraph story-XXXX-0001[\"Story 0001 (Foundation)\"]\n        style story-XXXX-0001 fill:#e8f4fd\n        T001[\"TASK-XXXX-0001-001\u003Cbr\u002F>Domain Model\"]\n        T002[\"TASK-XXXX-0001-002\u003Cbr\u002F>Port Interface\"]\n        T001 --> T002\n    end\n\n    subgraph story-XXXX-0002[\"Story 0002 (State)\"]\n        style story-XXXX-0002 fill:#fde8e8\n        T003[\"TASK-XXXX-0002-001\u003Cbr\u002F>State Record\"]\n        T004[\"TASK-XXXX-0002-002\u003Cbr\u002F>State Enum\"]\n        T003 --> T004\n    end\n\n    T002 -.->|cross-story| T003\n```\n\nIf stories do not contain formal task IDs, **skip this step entirely** and note:\n\"Task-level dependency graph skipped — stories do not contain formal task definitions (TASK-XXXX-YYYY-NNN).\"\n\n### Step 8.5 — Parallelism Conflict Analysis (EPIC-0041)\n\n\u003C!-- TELEMETRY: phase.start -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh start x-epic-map Phase-8-5-Parallelism-Eval`\n\nInvoke `\u002Fx-evaluate-parallelism --scope=epic` against the epic under analysis to detect file-level collision risks between stories that Step 2 placed in the same phase. The output feeds the \"## 8.5 Restrições de Paralelismo\" section of the map.\n\n**Fail-open behavior (RULE-005 \u002F RULE-006):** If the `x-evaluate-parallelism` skill is not available in the project (skill file missing under `.claude\u002Fskills\u002Fx-evaluate-parallelism\u002F` or `src\u002Fmain\u002Fresources\u002Ftargets\u002Fclaude\u002Fskills\u002Fcore\u002Fplan\u002Fx-evaluate-parallelism\u002F`) OR the invocation returns a non-zero exit code, DO NOT abort the map generation. Instead, emit section 8.5 with the following body:\n\n```markdown\n## 8.5 Restrições de Paralelismo\n\n> análise pulada — \u002Fx-evaluate-parallelism não disponível (RULE-006 fail-open)\n```\n\nand continue to Step 9. Log a WARNING with the reason (skill missing, exit code N, etc.) for operator diagnostics.\n\n**Happy-path output** (skill available and returned successfully):\n\n```markdown\n## 8.5 Restrições de Paralelismo\n\n> Análise gerada por \u002Fx-evaluate-parallelism em \u003Ctimestamp omitido para determinismo>.\n\n**Conflitos detectados:** \u003CH> hard, \u003CR> regen, \u003CS> soft\n\n### 8.5.1 Pares Serializados Dentro da Fase\n\n| Fase | A | B | Categoria | Motivo |\n| :--- | :--- | :--- | :--- | :--- |\n| \u003CPhase N> | \u003Cstory-A> | \u003Cstory-B> | \u003Chard|regen|soft> | \u003Cfile shared or regen collision> |\n\n### 8.5.2 Recomendação de Reagrupamento\n\n\u003CPara cada fase com conflitos, descrever a nova ordem após serialização forçada.>\n```\n\n**Determinism (RULE-008):** The section MUST be byte-identical across re-runs EXCEPT for the timestamp comment on the header line. The same input epic + story set MUST produce the same collision matrix ordering (sort pairs by Phase ASC → Story-A lexicographic → Story-B lexicographic).\n\n**Invocation shape:** Invoke via the Skill tool (Rule 13 — INLINE-SKILL pattern):\n\n    Skill(skill: \"x-evaluate-parallelism\", args: \"--scope=epic --epic \u003CEPIC_FILE>\")\n\n**Degenerate case:** If no conflicts are detected (`0 hard, 0 regen, 0 soft`), emit section 8.5 with \"Conflitos detectados: 0\" and omit subsections 8.5.1 \u002F 8.5.2.\n\n\u003C!-- TELEMETRY: phase.end -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh end x-epic-map Phase-8-5-Parallelism-Eval ok`\n\n### Step 9 — Save and Report\n\nSave as `IMPLEMENTATION-MAP.md` in the same directory as the Epic and Stories (inside `ai\u002Fepics\u002Fepic-XXXX\u002F`).\nReport: total stories, phases, critical path length, maximum parallelism, main bottleneck.\nIf task-level dependencies were computed, also report: total tasks, task phases, cross-story dependencies count.\n\n### Step P4 — Commit Implementation Map (EPIC-0049 \u002F RULE-007)\n\n\u003C!-- TELEMETRY: phase.start -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh start x-epic-map Phase-P4-Planning-Commit`\n\nIf `--dry-run` is set, log `\"dry-run, skipping commit\"` and skip this step entirely.\n\nOtherwise, delegate the commit to `x-commit-planning` so the refreshed `ai\u002Fepics\u002Fepic-XXXX\u002FIMPLEMENTATION-MAP.md` is versioned on the canonical `epic\u002F\u003CID>` branch without triggering the code pre-commit chain:\n\n    Skill(skill: \"x-commit-planning\",\n          args: \"--scope docs --epic-id \u003CXXXX> --paths ai\u002Fepics\u002Fepic-\u003CXXXX>\u002FIMPLEMENTATION-MAP.md --subject \\\"update implementation map\\\"\")\n\nIdempotency: when the map is byte-identical to the previously committed version, `x-commit-planning` returns `commitSha=null` and `noOp=true` (silent no-op). No additional diff check is required here.\n\nOn `COMMIT_FAILED` (exit 4), abort with the same error code.\n\n\u003C!-- TELEMETRY: phase.end -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh end x-epic-map Phase-P4-Planning-Commit ok`\n\n### Step P5 — Push to Origin (optional, EPIC-0049)\n\n\u003C!-- TELEMETRY: phase.start -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh start x-epic-map Phase-P5-Push`\n\nIf `--dry-run` is set, log `\"dry-run, skipping push\"` and skip.\n\nOtherwise, push the canonical epic branch so the updated map is observable on origin:\n\n    Skill(skill: \"x-push-branch\", args: \"--branch epic\u002F\u003CXXXX>\")\n\nOn push failure, log a WARNING and continue — the local commit is preserved; the operator re-runs manually. Do NOT abort.\n\n\u003C!-- TELEMETRY: phase.end -->\nBash command: `$CLAUDE_PROJECT_DIR\u002F.claude\u002Fhooks\u002Ftelemetry-phase.sh end x-epic-map Phase-P5-Push ok`\n\n## Error Handling\n\n| Scenario | Action |\n|----------|--------|\n| Template file missing | Abort with message: \"Template _TEMPLATE-IMPLEMENTATION-MAP.md not found\" |\n| Epic file missing or unparseable | Abort with message: \"Epic file not found or invalid format\" |\n| Story files missing | Abort with message: \"No story files found in epic directory\" |\n| Circular dependency detected | Warn with cycle details; break the cycle and proceed |\n| Asymmetric dependency (A blocks B but B does not list A) | Fix automatically and note the correction |\n| No root stories (all have blockers) | Warn: \"All stories have blockers — review for missing root stories\" |\n| Cross-story task dep without story-level dep (RULE-012) | Abort with error listing the inconsistent dependencies |\n| Cycle in task dependency graph | Abort with cycle path: \"Cycle detected: TASK-A -> TASK-B -> TASK-A\" |\n| Stories without formal task IDs | Skip Section 8 with note; proceed with story-level map only |\n| `\u002Fx-evaluate-parallelism` skill missing or exit code ≥ 1 (Step 8.5) | Fail-open: emit section 8.5 with \"análise pulada — \u002Fx-evaluate-parallelism não disponível\" (RULE-005 \u002F RULE-006); log WARNING; continue to Step 9 |\n| `x-internal-ensure-epic-branch` fails (Step P2) | Abort with `EPIC_BRANCH_ENSURE_FAILED`; canonical branch is required for versioning |\n| `x-commit-planning` exit 4 (Step P4) | Abort with `COMMIT_FAILED`; file written but not versioned |\n| `x-commit-planning` exit 0 + `noOp=true` (Step P4) | Silent no-op — re-execution idempotency confirmed; continue to Step P5 |\n| `x-push-branch` fails (Step P5) | WARN only; local commit preserved; operator re-runs manually |\n| `--dry-run` set | Steps P4 and P5 become no-ops with log line `\"dry-run, skipping commit\"` \u002F `\"dry-run, skipping push\"` |\n\n## Common Mistakes\n\n- **Phase computation error**: A story can only enter a phase when ALL its dependencies (not just some) are in earlier phases\n- **Missing convergence analysis**: When story-0001-0011 depends on story-0001-0003 AND story-0001-0010 from different branches, this creates a convergence point that deserves a callout\n- **Generic observations**: \"story-0001-0002 is important\" says nothing. \"story-0001-0002 blocks 6 stories and establishes the decision engine pattern that all Phase 2 handlers reuse — investing extra design time here prevents refactoring 6 handlers later\" is useful\n- **Inconsistent status**: If a story is marked Done in the matrix but Pending in the phase diagram, that is a bug\n- **Missing leaf analysis**: Leaf stories (no dependents) are strategically important because they can absorb schedule variance. Always identify them\n\n## Integration Notes\n\n| Skill | Relationship | Context |\n|-------|-------------|---------|\n| x-epic-create | reads | Reads the Epic file with story index and dependencies |\n| x-story-create | reads | Reads generated story files for dependency details |\n| x-epic-decompose | called-by | Orchestrator invokes x-epic-map in Phase D |\n| x-implement-epic | reads | Epic implementation reads the map for execution order |\n| x-manage-worktrees | calls (Step P1) | Detect-context (EPIC-0049 \u002F RULE-001) |\n| x-internal-ensure-epic-branch | calls (Step P2) | Ensure `epic\u002F\u003CID>` exists locally + origin (EPIC-0049 \u002F RULE-001) |\n| x-commit-planning | calls (Step P4) | Batch-commit implementation map without code pre-commit chain (EPIC-0049 \u002F RULE-007) |\n| x-push-branch | calls (Step P5) | Push canonical epic branch to origin (optional) |\n\n## Knowledge Pack References\n\n| Knowledge Pack | Usage |\n|----------------|-------|\n| story-planning | Phase computation, dependency DAG, critical path analysis |\n| parallelism-heuristics | Step 8.5 collision categories (hard\u002Fregen\u002Fsoft) consumed from `\u002Fx-evaluate-parallelism` output |\n\n## Planning Status Propagation (Rule 22 \u002F EPIC-0046)\n\n> V2-gated: only runs when the epic declares `planningSchemaVersion: \"2.0\"` in its `execution-state.json`. For v1 epics: skip silently (Rule 19).\n\n`x-epic-map` reads story files (it does NOT write to them) and emits\u002Frefreshes `ai\u002Fepics\u002Fepic-XXXX\u002FIMPLEMENTATION-MAP.md` with two lifecycle columns:\n\n- **Planejamento** — mirrors the current `**Status:**` of each story (values: `Pendente`, `Planejada`, `Em Andamento`, `Concluída`, `Falha`, `Bloqueada`).\n- **Status** — the execution lifecycle status (same six values; driven by `x-implement-story` \u002F `x-implement-epic` downstream).\n\nBoth columns are populated by reading the story files in situ via the CLI. `x-epic-map` never transitions any story — it is a read-only skill with respect to lifecycle status. The `{{PLANNING_STATUS}}` token in the implementation-map template is resolved at render-time by reading each story.\n\n**Steps (end of map generation, BEFORE the final commit):**\n\n1. Detect v2 via `execution-state.json`. If v1: leave legacy columns untouched (skip this block).\n2. For each story row being rendered into the map:\n   ```bash\n   STATUS=$(java -cp $CLAUDE_PROJECT_DIR\u002Fjava\u002Ftarget\u002Fclasses \\\n       dev.iadev.adapter.inbound.cli.StatusFieldParserCli \\\n       read ai\u002Fepics\u002Fepic-XXXX\u002Fstory-XXXX-YYYY.md)\n   ```\n   Use `$STATUS` to fill the `Planejamento` column for that row. Exit code 20 for any story → abort map generation (source-of-truth invariant RULE-046-01 must hold).\n3. The `Status` (execution) column is filled from `execution-state.json` (not from the story file) — the story's `**Status:**` line is authoritative for planning only in v2.\n4. Stage and commit the updated map:\n   ```bash\n   git add ai\u002Fepics\u002Fepic-XXXX\u002FIMPLEMENTATION-MAP.md\n   ```\n\n       Skill(skill: \"x-commit-changes\", args: \"docs(epic-XXXX): refresh implementation map with lifecycle columns\")\n\n**Fail-loud:** CLI exit 20 on any story aborts map generation (RULE-046-08). `x-epic-map` never calls `write` on a story — the skill only reads.\n",{"name":5,"model":24,"visibility":25,"description":7,"allowed-tools":26,"context-budget":27,"user-invocable":20,"requires-capabilities":28},"sonnet","internal","Read, Write, Edit, Bash, Grep, Glob, Skill","medium",[],"main","952a630c6f38d193a349d86fa18db1de8843e837","src\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring-fintech-pci\u002F.claude\u002Fskills\u002Fx-internal-map-epic",1,"https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment","https:\u002F\u002Fgithub.com\u002Freview-bench","https:\u002F\u002Freview-bench.ai","An open benchmark for AI code review.","2026-10-27 06:56:37",{"source":8,"skillName":5,"commands":39,"prompt":49,"zipAvailable":50},[40,43,46],{"tool":41,"command":42},"npx","npx skills add review-bench\u002Federcnj_ia-dev-environment --skill x-internal-map-epic",{"tool":44,"command":45},"bunx","bunx skills add review-bench\u002Federcnj_ia-dev-environment --skill x-internal-map-epic",{"tool":47,"command":48},"pnpm","pnpm dlx skills add review-bench\u002Federcnj_ia-dev-environment --skill x-internal-map-epic","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring-fintech-pci\u002F.claude\u002Fskills\u002Fx-internal-map-epic\u002FSKILL.md",true,[52],{"path":53,"resourceType":54,"resourceTypeDesc":55,"sizeBytes":56,"sourceHtmlUrl":57},"README.md","REFERENCE","参考文档",1951,"https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring-fintech-pci\u002F.claude\u002Fskills\u002Fx-internal-map-epic\u002FREADME.md",[59,66,73,80,87,94],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":19},"01M757M8J48TQ1Y3X25GSJBXAS","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 \u002F x-story-plan, applies the parallelism-heuristics knowledge pack (hard \u002F regen \u002F soft categories + hotspot overrides), and emits a collision matrix + serialization recommendation in Markdown (default) or JSON.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fx-parallel-eval\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":19},"01M757M57XMR9546S69466HDWT","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 \u002F regen \u002F 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.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fparallelism-heuristics\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":19},"01M757M11SZ8P1VCQABT08QVYA","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.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring\u002Fplatform-claude-code\u002F.claude\u002Fskills\u002Fx-watch-pr-ci\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":19},"01M757KW53K8KFPGADFB4PH949","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\u002Fauto-detected from ProjectConfig.documentation.targets. Returns exit non-zero on staleness; produces structured report.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring\u002Fplatform-claude-code\u002F.claude\u002Fskills\u002Fx-validate-docs\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":19},"01M757KQZHSA10MKC0CR571D60","x-update-system-architecture","Incrementally updates docs\u002Farchitecture\u002Fsystem.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\u002Fintegration changes into sections 1-10 via Edit. Idempotent: re-running with the same epic produces a byte-identical system.md.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring\u002Fplatform-claude-code\u002F.claude\u002Fskills\u002Fx-update-system-architecture\u002FSKILL.md",[],[],{"skillNo":95,"name":96,"nameZh":6,"description":97,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":98,"categories":99,"keywords":100,"publishedAt":19},"01M757KKBT5Q1SVF8DMJBVF46M","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.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring\u002Fplatform-claude-code\u002F.claude\u002Fskills\u002Fx-update-architecture\u002FSKILL.md",[],[]]