decompose

name	decompose
description	Decompose project or track into modules with dependency mapping. Project scope updates architecture.md and derives .ai-context.md. Track scope generates hld.md (always) and lld.md (when --lld or High-complexity module triggers it) — design-mandated artifacts that drive implement, deploy-checklist, and upload sign-off.

Decompose

You are decomposing a project or track into modules with clear responsibilities, dependencies, and implementation order.

MANDATORY GRAPH LOOKUP (read before any analysis)

First resolve the bundled helpers:

# Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
# is not exported into skill Bash). See core/shared/tool-resolver.md.
DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"

When draft/graph/schema.yaml exists, this skill must follow the graph-first lookup contract in core/shared/graph-query.md §Mandatory Lookup Contract. Module identification (Step 3) and dependency mapping (Step 4) start from the graph:

1. Query "$DRAFT_TOOLS/graph-arch.sh" --repo . for the authoritative module list and fan-in/out.
2. Run "$DRAFT_TOOLS/hotspot-rank.sh" --repo . to identify candidate modules to split.
3. Use "$DRAFT_TOOLS/graph-callers.sh"/"$DRAFT_TOOLS/graph-impact.sh" on demand for symbols/callers inside a candidate module.
4. Run "$DRAFT_TOOLS/cycle-detect.sh" --repo . to enumerate existing cycles before proposing new boundaries.

Filesystem grep/find for module discovery is only permitted after a documented graph miss, using the fallback sentence Graph returned no match for <X>; falling back to grep. and recorded in the Graph Usage Report.

Red Flags - STOP if you're:

See shared red flags — applies to all code-touching skills. In particular, the Ground-Truth Red Flags are load-bearing for decompose: HLD/LLD are design-mandated artifacts and TBD citations on Modified modules fail review.

Template contract: HLD/LLD/Plan emissions conform to core/shared/template-contract.md and core/shared/template-hygiene.md. The _TBD_<field>_ sentinel convention replaces Author1 / [e-mail] / [name] placeholders. After decompose runs, the verification gate chain in core/shared/verification-gates.md must pass clean on the regenerated set. Plan.md must back-link to ./discovery.md Phase 0 (Hotspots row IDs) per core/shared/discovery-schema.md.

Skill-specific:

• Defining modules without understanding the codebase
• Creating modules with circular dependencies
• Making modules too large (>3 files, excluding test files) or too small (single function)
• Skipping dependency analysis
• Not waiting for developer approval at checkpoints
• Emitting Citation: TBD for a module marked Status: Modified or Status: Existing (see §Step 5 Mandatory Citation Gate below)
• Leaving HLD §Checklist sections (Performance / Scale / Security / Resiliency / Multi-tenancy / Upgrade / Cost) as raw - placeholders instead of structured TBD bullets (see §Step 5a Checklist Scaffolding)

---

Standard File Metadata

ALL generated files MUST include the standard YAML frontmatter. This enables refresh tracking, sync verification, and traceability.

Gathering Git Information

Use the deterministic git-metadata.sh script (preferred) or the manual commands — both documented in core/shared/git-report-metadata.md, which contains the canonical resolver pattern for locating the script in any install layout. Both produce the same field set used in the YAML template below.

For track-scoped decomposition, also derive the human-readable track title used in the hld.md / lld.md H1:

• {TRACK_TITLE} — first-level heading text from the active track's spec.md (the # ... line). If spec.md has no H1, fall back to the {TRACK_ID}.

Also extract from spec.md frontmatter:

• classification.criticality, classification.data_classification, classification.deployment_surface — copy verbatim into hld.md frontmatter.
• approvers.* — pre-fill the HLD Approvals table (tech_leads, arb_leads, cloudops_leads, qa_leads, pm_leads) and LLD Approvals table (team_leads, tech_leads, qa). If a field is empty in spec.md, leave the table cell empty — do not invent names.

Metadata Template

Insert this stable YAML frontmatter at the top of every generated file. Git state lives in tracks/<track_id>/metadata.json — never in per-file frontmatter (WS-8).

---
project: "{PROJECT_NAME}"
module: "{MODULE_NAME or 'root'}"
track_id: "{TRACK_ID or null}"
generated_by: "draft:decompose"
generated_at: "{ISO_TIMESTAMP}"
# Stable frontmatter only (WS-8). Ephemeral fields live in metadata.json
# and render via <!-- META:<key> --> directives.
links:
  spec: "./spec.md"
---

Note: generated_by uses draft:command format (not /draft:command) for cross-platform compatibility. After writing HLD/LLD, update tracks/<track_id>/metadata.json with current git state and synced_to_commit.

---

Step 1: Determine Scope

Parse $ARGUMENTS for flags first, then strip them before interpreting the remaining text as scope:

• --lld → LLD mode — generate Section 6 (Low-Level Design) in addition to HLD. Strip from arguments before scope detection.

Scope detection (on stripped arguments):

• project or no argument with no active track → Project-wide decomposition → draft/architecture.md + draft/.ai-context.md
• Track ID or active track exists → Track-scoped decomposition → draft/tracks/<id>/hld.md (always) + draft/tracks/<id>/lld.md (when triggered)

LLD auto-trigger: Even without --lld, LLD is generated automatically when any module in Step 3 is marked Complexity: High. Tell the developer when this triggers: "One or more modules are High complexity — generating LLD automatically."

No legacy track-architecture.md: That artifact has been retired. New tracks always use hld.md (and lld.md when triggered). Existing tracks that have a track-architecture.md are not migrated automatically — leave them alone; new tracks get the new format.

Pre-Generation Sanity Checks (Track-Scoped Only)

Before Step 2, run these checks and prompt the developer when triggered. Do not silently proceed.

1. Spec readiness — read draft/tracks/<id>/spec.md frontmatter and first 20 lines:

   • If spec.md is missing → ERROR: "No spec.md for track <id>. Run /draft:new-track first." Halt.
   • If spec.md contains Status: [ ] Drafting or spec-draft.md still exists → WARN: "Spec for <id> is still in draft. HLD generated against a draft spec will need rework. Continue anyway? [y/N]" — default No.
   • If classification.criticality is unset or still placeholder ({...}) → WARN: "Classification not set in spec.md frontmatter — HLD Approvals gate (/draft:upload) will not engage correctly for high-criticality tracks. Continue? [y/N]".

2. Existing artifacts — check what already exists:

   • If hld.md exists → ASK: "hld.md already exists for <id>. (1) Overwrite, (2) Skip HLD and only generate LLD, (3) Cancel." Default (3).
   • If lld.md exists and LLD will be regenerated → ASK same 3-way choice.

Only proceed to Step 2 after the developer resolves each prompt.

Step 2: Load Context

1. Read draft/product.md for product understanding
2. Read draft/tech-stack.md for technical patterns
3. If track-scoped:
   • Read track's spec.md for requirements
   • Read track's plan.md for existing task breakdown

For brownfield projects, scan the existing codebase using these concrete steps:

Codebase Scanning Patterns

Directory structure — Map top-level organization:

ls -d src/*/ lib/*/ app/*/ packages/*/ 2>/dev/null

Entry points — Find main files and exports:

• Look for: index.ts, main.ts, app.ts, mod.rs, __init__.py, main.go
• Check package.json main/exports fields, pyproject.toml entry points, go.mod module path

Existing module boundaries — Identify by:

• Directory-per-feature patterns (e.g., src/auth/, src/users/)
• Package files (package.json in subdirs, __init__.py, go package declarations)
• Barrel exports (index.ts re-exporting from a directory)

Dependency patterns — Trace imports:

• Search for import / require / from statements across source files
• Identify which directories import from which other directories
• Flag cross-cutting imports (e.g., utils/ imported everywhere)

File type filters by language:

Language	Source Extensions	Config Files
TypeScript/JS	*.ts, *.tsx, *.js, *.jsx	tsconfig.json, package.json
Python	*.py	pyproject.toml, setup.py, requirements.txt
Go	*.go	go.mod, go.sum
Rust	*.rs	Cargo.toml

What to ignore: node_modules/, __pycache__/, target/, dist/, build/, .git/, vendored dependencies. Always respect .gitignore and .claudeignore.

Graph-Accelerated Discovery (MANDATORY when draft/graph/ exists)

When graph data is available, the graph is the primary (not optional) source for module discovery — manual scanning above is reserved for the graph-miss fallback path:

• Module boundaries: Query "$DRAFT_TOOLS/graph-arch.sh" --repo . — module list with node counts and per-language file counts
• Dependency edges: Weighted inter-module dependencies with exact include counts — replaces manual import tracing
• Cycle detection: Circular dependency paths already computed — use for identifying tight coupling and decomposition candidates
• Hotspots: Run "$DRAFT_TOOLS/hotspot-rank.sh" --repo . — high-complexity files that may need further decomposition
• Per-module detail: query "$DRAFT_TOOLS/graph-callers.sh"/"$DRAFT_TOOLS/graph-impact.sh" for symbol/call detail within modules of interest

This data is deterministic and exhaustive. The manual scanning recipes above only run after the graph misses on the concept the user named — and the miss must be reported in the Graph Usage Report footer. See core/shared/graph-query.md §Concept-to-Files Recipe.

Step 3: Module Identification

Propose a module breakdown through dialogue:

For each module, define:

• Name - Short, descriptive identifier
• Responsibility - One sentence: what this module owns
• Files - Expected source files (existing or to be created)
• API Surface - Public functions, classes, or interfaces
• Dependencies - Which other modules it imports from
• Complexity - Low / Medium / High

Module Guidelines (see core/agents/architect.md)

1. Each module should have a single responsibility
2. Target 1-3 files per module
3. Every module needs a clear API boundary
4. Minimal Coupling — communicate through interfaces, not internals

• Modules should be testable in isolation
• Each module typically contains: API, control flow, execution state, functions

CHECKPOINT (MANDATORY)

STOP. Present the module breakdown to the developer.

---
                   MODULE BREAKDOWN
---
Scope: [Project / Track: <track-id>]

MODULE 1: [name]
  Responsibility: [one sentence]
  Files: [file list]
  API: [public interface summary]
  Dependencies: [none / module names]
  Complexity: [Low/Medium/High]

MODULE 2: [name]
  ...

---

Wait for developer approval. Developer may add, remove, rename, or reorganize modules.

Step 4: Dependency Mapping

After modules are approved:

1. Map dependencies - For each module, list what it imports from other modules
2. Detect cycles - If circular dependencies exist, propose how to break them (extract shared interface into new module)
3. Generate ASCII diagram - Visual representation of dependency graph
4. Generate dependency table - Tabular format for reference
5. Determine implementation order - Topological sort (implement leaves first, then dependents)

CHECKPOINT (MANDATORY)

STOP. Present the dependency diagram and implementation order.

---
                 DEPENDENCY ANALYSIS
---
DIAGRAM
---
[auth] ──> [database]
   │ │
   └──> [config] <──┘
            │
      [logging] (no deps)

TABLE
---
Module | Depends On | Depended By
---------- | ----------------- | -----------------
logging | - | auth, database, config
config | logging | auth, database
database | config, logging | auth
auth | database, config | -

IMPLEMENTATION ORDER
---
1. logging (leaf - no dependencies)
2. config (depends on: logging)
3. database (depends on: config, logging)
4. auth (depends on: database, config)

Parallel opportunities: config and database can start after logging.
---

Wait for developer approval.

Step 5: Generate Design Documents

Template selection depends on scope:

• Project-wide → core/templates/architecture.md (full 28-section engineering reference)
• Track-scoped → core/templates/hld.md (always) and core/templates/lld.md (when triggered)

Output location:

• Project-wide: Update draft/architecture.md with the module changes, then run the Condensation Subroutine (defined in core/shared/condensation.md) to regenerate draft/.ai-context.md.
• Track-scoped: write to draft/tracks/<id>/hld.md and (when triggered) draft/tracks/<id>/lld.md.

Context: HLD and LLD are design-mandated review artifacts. HLD is approved by Technical Leads / Architecture Review Board / Cloud Operations / QA / PM Leads before significant implementation; LLD is approved by Team Leads / Technical Leads / QA before code review begins. /draft:upload gates git upload for high-criticality tracks on the HLD Approvals table being populated.

Step 5a: HLD Generation (Track-Scoped, Always)

Generate draft/tracks/<id>/hld.md from core/templates/hld.md. Populate every section that has a directive — do not ship placeholders.

Frontmatter:

• Copy git metadata from current repo state.
• Copy classification.* from spec.md frontmatter (criticality, data_classification, deployment_surface). The HLD's links.* block is statically correct in core/templates/hld.md — do not copy it from spec.md.

Approvals table: Pre-fill from spec.md approvers.* frontmatter. Empty values stay empty — do not invent names.

§Background: ½–1 page. Pull from spec.md §Problem Statement and §Background & Why Now. Tighten for HLD audience (focus on the "why now" and the system context).

§Requirements: Do not duplicate spec.md. Verify the link references resolve to actual sections in spec.md; if a section is missing, flag it.

§High Level Design / Architecture:

• <!-- GRAPH:track-component-diagram --> slot: Render Mermaid flowchart TD with three subgraphs — Track (modules in scope from Step 3), Existing (existing modules this track touches per integration edges), External (DB, queue, 3P APIs). Label edges with transport (HTTP / RPC / queue / direct call) when non-obvious.
• Architecture narrative (≤300 words). Explain how blackbox requirements map to the architecture. Name the architectural style. Justify from observable evidence.

§High Level Design / UI Architecture Changes: Populate only if the track touches UI; otherwise write N/A — backend-only track.

§High Level Design / Key Design Decisions: 2–5 bullet decisions, each with a one-sentence "Why:" referencing an observable constraint (latency budget, multi-tenant isolation requirement, regulatory compliance), not aesthetics.

§High Level Design / Alternatives Considered: Table format. Promote any non-trivial rejected alternative to a standalone ADR via /draft:adr and link both ways.

§Detailed Design:

• <!-- GRAPH:track-component-table --> slot: Render one row per module from Step 3. Columns: Module, Status (New/Modified/Existing), Files (count + comma list), Public API count, Fan-In, Fan-Out, Complexity (Low/Medium/High), Primary Deps, Citation (path:line of entry symbol).
• Mandatory Citation Gate: For every row whose Status is Modified or Existing, the Citation cell MUST resolve to a real path:line from a file you Read in this run. TBD is only legal for Status: New rows, and only when the planned file path is filled (e.g. Citation: newscribe/server/ops/shuffle_memory_eligibility.h (planned)). If a Modified-row Citation is unresolved, halt — Read the file, locate the entry symbol, and fill the cell before emitting the table. See graph-query.md §Ground-Truth Discipline rules G1 and G3.
• Per-component subsection: One #### {Component Name} block per module. Fill Responsibility, Status, Entry point (resolved path:line for Modified/Existing modules), Public API link to LLD, Whitebox requirements addressed (AC IDs from spec.md), Design notes (≤200 words).

§Dependencies:

• <!-- GRAPH:track-dependencies --> slot: Render rows per cross-module integration edge of kind call/import/event/shared-schema. Columns: Dependent Component, Edge Kind, Impact Assessment (Small/Medium/Large — graph fan-in heuristic: 1–2 = Small, 3–5 = Medium, 6+ = Large), Description, Citation. The Citation column is bound by the same Mandatory Citation Gate as the component table.

§Intellectual Property, §Checklist, §Deployment, §Observability: These are author-driven sections that the design author completes before the HLD is presented for approval. Decompose's job is to scaffold structured TBD bullets, not to invent claims and not to leave bare - placeholders.

Checklist Scaffolding (mandatory)

For criticality: standard | high | mission-critical tracks, replace bare - placeholders in HLD §Checklist with structured TBD bullets. This turns blank review-gate sections into a concrete punch-list. Bullets vary by section:

### Performance
- [ ] **Latency budget (p50/p95/p99):** TBD — fill before HLD review
- [ ] **Throughput target:** TBD
- [ ] **Resource budget (CPU / RAM / IO per node):** TBD
- [ ] **Baseline measurement methodology:** TBD — name benchmark or production dashboard

### Scale
- [ ] **Per-tenant / per-node limits:** TBD
- [ ] **Growth assumptions (1y / 3y):** TBD
- [ ] **Scaling axis (vertical / horizontal / partitioning):** TBD

### Security
- [ ] **Threat model reference:** TBD — link STRIDE doc or write inline
- [ ] **Auth / authz changes:** TBD (none / list)
- [ ] **Data classification touched:** TBD
- [ ] **Secrets / credentials surface:** TBD (none / list)

### Resiliency
- [ ] **Failure modes considered:** TBD
- [ ] **Crash / restart semantics:** TBD
- [ ] **Backpressure / circuit-breaker:** TBD
- [ ] **Rollback path:** TBD

### Multi-tenancy
- [ ] **Tenant isolation invariants preserved:** TBD (or N/A — single-tenant)
- [ ] **Noisy-neighbor risks:** TBD

### Upgrade
- [ ] **Forward compatibility (old reading new):** TBD
- [ ] **Backward compatibility (new reading old):** TBD
- [ ] **Mixed-version cluster behavior:** TBD
- [ ] **Migration / backfill required:** TBD

### Flags and Controlled Rollout of Features
- [ ] **Master flag name (default value):** TBD
- [ ] **Cluster feature gate (if any):** TBD
- [ ] **Rollout phases:** TBD
- [ ] **Kill switch:** TBD

### Cost Implications
- [ ] **Incremental CPU / RAM / IO / storage:** TBD
- [ ] **Cloud cost delta (if SaaS):** TBD or N/A

For criticality: low quick tracks, the bare - placeholder is acceptable — these sections are not gated by /draft:upload for low criticality.

The TBD bullets are not claims. They are reviewable gaps. A reviewer can ask "is the latency budget defined yet?" and the author can fill it. Bare - placeholders give the reviewer nothing to ask about.

TPT/IDF automation deferred — when MCP integration to Jira ships, decompose will pre-fill the §IP TPT table from existing TPT JIRA issues. Today: section stays empty for the author.

Step 5b: LLD Generation (Gated)

Trigger: --lld flag was passed in Step 1 OR any module in Step 3 has Complexity: High.

Skip condition: No --lld flag and no High-complexity module. Do not create lld.md. Note in completion announcement: "LLD not generated. Run /draft:decompose --lld to expand."

When triggered, generate draft/tracks/<id>/lld.md from core/templates/lld.md. Refer to core/agents/architect.md for contract-design conventions.

Frontmatter: Copy git metadata + links.* (point hld link at ./hld.md).

Approvals table: Pre-fill from spec.md approvers.{team_leads, tech_leads, qa} (flat keys, no lld_ prefix).

§Background: Single sentence linking to HLD §Background. Add component-internal context only if HLD doesn't cover it.

§Requirements: Link-only to spec.md; list AC IDs covered by this LLD.

§Low Level Design / Classes and Interfaces:

• <!-- GRAPH:track-class-table --> slot: Render per-module table from graph public-API index. One row per public symbol. Columns: Symbol, Kind (class/iface/func/method), Signature, Visibility, Citation (path:line), Concurrency Notes.
• Mandatory Citation Gate (LLD): Same rule as HLD §Detailed Design. For every symbol whose owning module has Status Modified or Existing, Citation must resolve to a real path:line from a file Read in this run. For Status: New symbols, Citation may be <planned path>:<planned line or TBD> provided the file path is concrete. A bare TBD cell is a halt — fix before emitting.
• Per-component subsection: Public API table with full signatures, params, returns, errors, citation. Document Preconditions, Postconditions, Invariants (thread safety, idempotency, ordering).

§Low Level Design / Data Model:

• <!-- GRAPH:track-data-models --> slot: Render one block per new/modified entity. Pull proto/struct/class declarations and field metadata from the graph data-model index.
• Per-model subsection: Field table (type, nullable, default, validation), Storage, Indexes/Keys, Migration path.

§Low Level Design / Key Algorithms and Workflows: Sequence diagram per AC that crosses more than one module — happy path + at least one error path. Annotate gates with Note over. For genuinely non-trivial logic: pseudocode with declared inputs, outputs, time/space complexity, edge cases. Skip for straightforward CRUD.

§Low Level Design / Error Handling & Retry Semantics: One row per operation with non-trivial error handling. Classify each error, specify retry policy, backoff, max attempts, fallback. Document circuit-breaker thresholds and idempotency keys.

§Low Level Design / Refactoring of Existing Code: Populate when the track refactors existing code; otherwise leave empty.

§Low Level Design / Programming Language Choice and Unit Testing: Author-driven. Reference /draft:testing-strategy for project-level test strategy; LLD section covers only what is component-specific.

§Low Level Design / PaaS Choices: Author-driven. Decompose does not infer Data Store / Workflow Engine / Checkpointing choices.

§Observability / Metrics + Alerting Thresholds: Author-driven. /draft:deploy-checklist validates this table is populated before deploy.

Step 5c: Normalise Whitespace

After writing all generated files, strip trailing whitespace and blank lines at EOF. GitHub rejects commits containing either.

Resolve the script via the canonical tool resolver (see core/shared/tool-resolver.md):

# Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
# is not exported into skill Bash). See core/shared/tool-resolver.md.
DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
# Fix all generated markdown for this track:
[ -x "$DRAFT_TOOLS/fix-whitespace.sh" ] && bash "$DRAFT_TOOLS/fix-whitespace.sh" --track <id>
# Also fix project-level files if architecture.md was touched:
[ -x "$DRAFT_TOOLS/fix-whitespace.sh" ] && bash "$DRAFT_TOOLS/fix-whitespace.sh" draft/architecture.md draft/.ai-context.md 2>/dev/null || true

Run unconditionally — idempotent if files are already clean.

CHECKPOINT (MANDATORY)

STOP. Present the generated hld.md (and lld.md if generated) to the developer. Call out:

• Which graph slots were populated vs. unpopulated (and why — e.g., "no proto definitions found, GRAPH:track-data-models slot empty").
• Whether LLD was generated, and the trigger (--lld flag or auto-triggered by High-complexity module X).
• Author-driven sections that still need manual content: §IP, §Checklist (HLD), §PaaS/§UT (LLD), §Observability metrics/thresholds.
• Reminder: HLD must be circulated to the approvers in the Approvals table before significant implementation begins; /draft:upload will block git upload for high-criticality tracks until the table is signed.

Wait for developer approval before proceeding to Step 6.

Step 6: Update Plan (Track-Scoped Only)

If this is a track-scoped decomposition and a plan.md exists:

1. Review existing phases against the module implementation order
2. Propose restructuring phases to align with module boundaries
3. Each module becomes a phase or maps to existing phases

Bracketed-region rewriting (WS-6)

core/templates/plan.md (and tracks generated from it at template_version ≥ 2.0.0) wraps phase tables in:

<!-- DECOMPOSE:REGENERATE START -->
... phase tables ...
<!-- DECOMPOSE:REGENERATE END -->

Decompose only rewrites content between these markers. Manual notes the author added above or below the markers (overview prose, design notes, references, sunset criteria) survive every regenerate. After rewriting:

1. Update plan.md generated_by: to draft:decompose.
2. Update plan.md generated_at: to the current ISO-8601 timestamp.
3. Ensure plan.md generated_at ≥ sibling hld.md / lld.md generated_at (the hygiene validator fails on stale plan).
4. Run "$DRAFT_TOOLS/check-track-hygiene.sh" <track_dir> and resolve any findings before promoting status past draft.

If the plan does not yet have the bracket markers (pre-2.0 track), insert them around the phase region during this first decompose run, then rewrite.

Plan Merge Rules

When restructuring plan.md around modules, follow these rules for existing tasks:

Completed tasks [x]: Preserve exactly as-is. Map them to the appropriate module phase. Do not rename, reorder, or modify. Add a note: (preserved from original plan).

In-progress tasks [~]: Map to the appropriate module phase. Flag for developer review if the task spans multiple modules:

- [~] **Task 2.1:** Original task description
  - ⚠ REVIEW: This task may need splitting across modules [auth] and [database]

Pending tasks [ ]: Remap freely to module phases. Split tasks that span module boundaries into per-module tasks. Preserve the original task description in the new task.

Blocked tasks [!]: Preserve the blocked status and reason. Map to appropriate module. If the blocker is in a different module, add a cross-module dependency note.

Conflict handling: If a task doesn't map cleanly to any module:

1. List it under a ### Unmapped Tasks section at the end
2. Flag it for developer decision
3. Never silently drop tasks

CHECKPOINT (MANDATORY)

STOP. Present the updated plan structure.

PROPOSED PLAN RESTRUCTURE
---
Phase 1: [Module A] (Foundation)
  - Task 1.1: [existing or new task]
  - Task 1.2: ...

Phase 2: [Module B] (depends on Module A)
  - Task 2.1: ...
  ...

Wait for developer approval before writing changes to plan.md.

Step 6b: Sync Metadata After Restructuring

After applying the approved plan changes:

1. Update tracks/<track_id>/metadata.json: Set phases.total to match the new number of phases. Also update git.commit, git.commit_message, git.dirty, and synced_to_commit to current HEAD — this is the single source of truth for the track's git state.
2. Update draft/tracks.md: Update the phase count for this track's entry to reflect the new total (e.g., Phase: 0/4 → Phase: 0/5 if a phase was added).

Completion

Track-scoped announcement:

Track decomposition complete.

Created: draft/tracks/<id>/hld.md
        [if LLD generated:] draft/tracks/<id>/lld.md
        [else:] (LLD not generated — run /draft:decompose --lld to expand)

Modules: [count]
Implementation order: [module names in order]

Author-driven sections still empty (fill before HLD review):
- HLD §Intellectual Property (Inventions, IDFs, TPT)
- HLD §Checklist (Performance, Scale, Security, Resiliency, Multi-tenancy, Upgrade, Cost)
- HLD §Deployment, §Observability
[if LLD generated:]
- LLD §Programming Language Choice, §PaaS Choices, §Observability metrics/thresholds

Next steps:
- Fill the author-driven sections in hld.md (and lld.md if present)
- Circulate hld.md to approvers listed in §Approvals
- Run /draft:implement to start building once HLD is approved
- /draft:upload will block git upload on HLD Approvals being signed
  for criticality ∈ {high, mission-critical}

Project-wide announcement (when scope = project):

Project architecture refresh complete.

Updated: draft/architecture.md
Derived: draft/.ai-context.md

Next steps:
- Review architecture.md and edit as needed
- For new feature work: /draft:new-track then /draft:decompose

Mutation Protocol for architecture.md and .ai-context.md (Project-Wide)

draft/architecture.md is the source of truth. draft/.ai-context.md is derived from it via the Condensation Subroutine (defined in core/shared/condensation.md). Always update architecture.md first, then regenerate .ai-context.md.

When adding new modules to the project-wide architecture:

1. Update draft/architecture.md: append module definitions, update dependency diagram and table
2. Do NOT remove/modify [x] Existing modules
3. Update draft/metadata.json with current HEAD (use git-metadata.sh --project-metadata --generated-by "draft:decompose" or update git.commit, git.commit_message, and synced_to_commit manually)
4. Run the Condensation Subroutine (defined in core/shared/condensation.md) to regenerate draft/.ai-context.md

Safe write pattern for architecture.md:

1. Backup architecture.md → architecture.md.backup
2. Write changes to architecture.md.new
3. Present diff for review
4. On approval: replace architecture.md with architecture.md.new, run Condensation Subroutine, then delete architecture.md.backup
5. On rejection: delete architecture.md.new and rename architecture.md.backup back to architecture.md

Updating design context

Project-wide rerun (running /draft:decompose on existing .ai-context.md / architecture.md):

1. Read the existing context file
2. Ask developer what changed (new modules, removed modules, restructured boundaries)
3. Follow the same checkpoint process for changes
4. Update draft/architecture.md, preserving completed module statuses and stories, then regenerate .ai-context.md

Track-scoped rerun (running /draft:decompose <track> on existing hld.md / lld.md):

1. Read the existing HLD (and LLD if present)
2. If the track's spec.md has materially changed, prefer /draft:change first to amend spec/plan and flag HLD/LLD impact
3. Otherwise, regenerate the graph-fenced slots only (component diagram, component table, dependencies table, class table, data models). Author-driven sections (§IP, §Checklist, §PaaS, §UT, §Observability) and the §Approvals table are preserved verbatim
4. If the Approvals table had signatures and the HLD's structural sections changed, surface a warning: "HLD modified after sign-off — re-circulate to approvers."

---

Cross-Skill Dispatch

After Module Decomposition

After defining module boundaries and interfaces:

"Decomposition complete. Consider:

Testing:
  → /draft:testing-strategy — Define per-module test boundaries and integration test strategy

Documentation:
  → /draft:documentation api <module> — Document public module interfaces

Architecture:
  → /draft:adr "Module boundary decisions for {project}" — Record decomposition rationale"

Dependency Cycle Detection

If dependency analysis (Step 4) detects cycles or high coupling:

"Detected dependency cycles / high coupling. Consider:
  → /draft:tech-debt — Catalog architecture debt and prioritize remediation"

ADR Auto-Invocation

When decomposition involves breaking a monolith, choosing module boundaries, or extracting services:

• Auto-invoke: "This decomposition is a significant architectural decision. Creating ADR to document rationale."
• Invoke /draft:adr "Module boundary decisions for {project}"

Mandatory Self-Check (before completion announcement)

Before printing the completion announcement, internally verify and report:

1. Graph data queried — which live-engine tools were invoked (e.g. get_architecture, hotspot-rank.sh, cycle-detect.sh).
2. Layer 1 files deliberately skipped — list any .ai-context.md sections, tech-stack.md, product.md, workflow.md you skipped as irrelevant to this decomposition. Be explicit; do not silently skip.
3. Filesystem grep fallback justification — for every grep/find run, state the concept it searched for and quote the graph-miss sentence.
4. Citation Gate audit — scan every Citation column in the generated component table, dependencies table, and LLD class table. Report:
   • Modified/Existing rows with resolved citations: count
   • Modified/Existing rows with TBD citations: must be 0 (halt and fix if non-zero)
   • New rows with (planned) paths: count
5. Files actually Read — list each source file opened during this run. Cross-reference: every Modified/Existing row in the component table must trace to at least one file in this list.
6. HLD Checklist scaffolding — confirm Performance / Scale / Security / Resiliency / Multi-tenancy / Upgrade / Flags / Cost are populated with structured TBD bullets (for criticality: standard | high | mission-critical), not bare - placeholders.

If draft/graph/schema.yaml does not exist, set Graph files queried: NONE and use justification graph data unavailable. Decompose must still propose modules from .ai-context.md / source files in that case and must still Read those files to satisfy the Citation Gate.

Graph Usage Report (append to output)

Emit the canonical footer from core/shared/graph-usage-report.md §Canonical footer. The lint hook scripts/tools/check-graph-usage-report.sh validates the section on save.

Skill Telemetry

As the last step after the completion announcement, emit a metrics record. Best-effort — never block.

Payload fields:

{
  "skill": "decompose",
  "scope": "track|project",
  "track_id": "<track_id or null>",
  "modules_count": <N>,
  "lld_generated": true|false,
  "high_complexity_modules": <N>
}

Emit call:

# Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
# is not exported into skill Bash). See core/shared/tool-resolver.md.
DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
[ -x "$DRAFT_TOOLS/emit-skill-metrics.sh" ] && bash "$DRAFT_TOOLS/emit-skill-metrics.sh" \
  '{"skill":"decompose","scope":"<scope>","track_id":"<id_or_null>","modules_count":<N>,"lld_generated":<bool>,"high_complexity_modules":<N>}'