dep-map · diff
v1.0.0 to v1.0.0
141 added, 70 removed. Audit A to A.
---
name: dep-map
- description: Maps dependencies between engineering stories, computes optimal implementation order with parallel batches, and flags circular dependencies.
- version: "1.0.0"
+ description: "Maps dependencies between stories, code modules, tickets, or specs. Computes optimal implementation order with parallel batches, cycle detection, and critical path analysis."
+ version: 1.0.0
category: analysis
platforms:
- CLAUDE_CODE
---
- You are a dependency mapping agent. Analyze stories and produce an optimal implementation plan.
+ You are a dependency mapping agent. Analyze items and produce an optimal implementation plan.
Do NOT ask the user questions.
INPUT: $ARGUMENTS
One of:
- - A file path containing stories (from /backend-spec output)
- - A list of story descriptions
- - "scan" to find all story/spec files in the current directory
- If no arguments, scan the current directory for `.md` files containing story specs.
+ - A file path or glob pattern containing stories, specs, or source code
+ - A list of story/ticket descriptions
+ - A GitHub Issues URL or Linear project URL
+ - "scan" to auto-detect all relevant files in the current directory
+ - "code" to analyze code module dependencies (imports, packages)
+ If no arguments, scan the current directory for `.md` files containing specs/stories
+ AND source code files to detect the most useful dependency analysis.
+
============================================================
- PHASE 1: PARSE STORIES
+ PHASE 0: DETECT INPUT TYPE
============================================================
- For each story found, extract:
- 1. **Title / Story ID** (e.g., "BE-Auth: User Registration", "FE-Profile: User Dashboard")
- 2. **Type:** Backend (BE) or Frontend (FE) — infer from routes, schemas, or UI references
+ Determine what kind of dependency analysis is needed:
+
+ **A) Story/Spec Dependencies** — markdown specs, Jira stories, GitHub Issues, Linear tickets
+ **B) Code Module Dependencies** — import graphs, package.json, requirements.txt, go.mod, pubspec.yaml, Cargo.toml
+ **C) Mixed** — stories that reference code modules, or code that maps to planned work items
+
+ For GitHub Issues: use `gh issue list` and `gh issue view` to fetch issue bodies.
+ For Linear tickets: parse provided markdown exports or URLs.
+ For code: read source files and parse import/require/include statements.
+
+ ============================================================
+ PHASE 1: PARSE ITEMS
+ ============================================================
+
+ ### For Stories / Specs / Tickets
+
+ For each item found, extract:
+ 1. **Title / ID** (e.g., "BE-Auth: User Registration", "FE-Profile: User Dashboard", "#42")
+ 2. **Type:** Backend (BE), Frontend (FE), Infrastructure (INFRA), or Full-Stack (FS) — infer from content
3. **Tables/Collections referenced** — extract from Dev Notes, schema sections, or SQL
- 4. **Endpoints produced** — API routes this story creates (for BE stories)
- 5. **Endpoints consumed** — API routes this story needs (for FE stories)
- 6. **Explicit dependencies** — "Depends on STORY-XXX" or "Requires X to exist"
- 7. **Models/Types shared** — data models used across stories
+ 4. **Endpoints produced** — API routes this item creates (for BE items)
+ 5. **Endpoints consumed** — API routes this item needs (for FE items)
+ 6. **Explicit dependencies** — "Depends on X", "Blocked by #Y", "Requires Z to exist"
+ 7. **Models/Types shared** — data models used across items
+ 8. **Complexity estimate** — S (< 2h), M (2-4h), L (4-8h), XL (8h+) based on scope
- If stories are in Jira format (from /backend-spec), parse:
+ If items are in Jira format (from /spec), parse:
- Routes section for endpoint paths
- Dev Notes for table names and schema references
- Acceptance Criteria for functional dependencies
+ ### For Code Modules
+
+ For each module/package, extract:
+ 1. **Module path** — file path or package name
+ 2. **Imports** — what this module imports (direct dependencies)
+ 3. **Exports** — what this module exposes (public API surface)
+ 4. **Package dependencies** — external packages from manifest files
+ 5. **Shared types** — types/interfaces imported by multiple modules
+
+ Scan these files for dependency information:
+ - **JS/TS:** `import`/`require` statements, `package.json`
+ - **Python:** `import`/`from` statements, `requirements.txt`, `pyproject.toml`
+ - **Go:** `import` blocks, `go.mod`
+ - **Rust:** `use` statements, `Cargo.toml`
+ - **Dart/Flutter:** `import` statements, `pubspec.yaml`
+ - **Java/Kotlin:** `import` statements, `build.gradle`, `pom.xml`
+
============================================================
PHASE 2: BUILD DEPENDENCY GRAPH
============================================================
- For each story pair (A, B), check for dependencies:
-
- 1. **Table dependency:** Story B uses a table/collection that Story A creates.
- → B depends on A.
+ ### For Stories / Specs
- 2. **API dependency:** Story B (FE) consumes an endpoint that Story A (BE) creates.
- → B depends on A.
+ For each item pair (A, B), check for dependencies:
- 3. **Data dependency:** Story B uses a model/type that Story A defines.
- → B depends on A.
+ 1. **Table dependency:** B uses a table/collection that A creates. -> B depends on A.
+ 2. **API dependency:** B (FE) consumes an endpoint that A (BE) creates. -> B depends on A.
+ 3. **Data dependency:** B uses a model/type that A defines. -> B depends on A.
+ 4. **Explicit dependency:** B references A by name or ID. -> B depends on A.
+ 5. **Schema dependency:** B alters a table that A creates. -> B depends on A.
- 4. **Explicit dependency:** Story B references Story A by name or ID.
- → B depends on A.
+ ### For Code Modules
- 5. **Schema dependency:** Story B alters a table that Story A creates.
- → B depends on A.
+ 1. **Import dependency:** Module B imports from Module A. -> B depends on A.
+ 2. **Package dependency:** Package B lists Package A as a dependency.
+ 3. **Type dependency:** Module B uses a type/interface defined in Module A.
+ 4. **Re-export dependency:** Module B re-exports from Module A.
- Build an adjacency list: `{ storyId: [depends_on_ids] }`
+ Build an adjacency list: `{ itemId: [depends_on_ids] }`
============================================================
PHASE 3: DETECT ISSUES
============================================================
1. **Circular dependencies:** Run cycle detection on the graph.
- If found: CRITICAL — list the cycle and suggest how to break it
- (usually by splitting a story or extracting a shared foundation story).
+ If found: CRITICAL — list each cycle with the exact items involved.
+ Provide specific cycle-breaking recommendations:
+ - For stories: suggest splitting a story or extracting a shared foundation item
+ - For code: suggest extracting shared interfaces to a common module,
+ using dependency inversion (depend on abstractions), or lazy loading
- 2. **Missing dependencies:** Story references a table/endpoint/model that no story creates.
- WARN — either the dependency exists in the codebase already, or a story is missing.
+ 2. **Missing dependencies:** Item references a table/endpoint/model/module that nothing provides.
+ WARN — either the dependency exists in the codebase already, or an item is missing.
- 3. **Orphan stories:** Stories with no dependencies and nothing depends on them.
+ 3. **Orphan items:** Items with no dependencies and nothing depends on them.
INFO — these can be implemented at any time.
- 4. **Long chains:** Dependency chains longer than 4 stories.
+ 4. **Long chains:** Dependency chains longer than 4 items.
WARN — bottleneck risk. Consider parallelizing or splitting.
+ 5. **High fan-in:** Items that 5+ other items depend on.
+ WARN — high-risk item. If delayed, it blocks many downstream items. Prioritize.
+
+ 6. **High fan-out:** Items that depend on 5+ other items.
+ WARN — integration risk. Likely to be blocked frequently. Consider splitting.
+
============================================================
PHASE 4: COMPUTE OPTIMAL ORDER
============================================================
1. Run topological sort on the dependency graph.
- 2. Group stories into parallel batches:
- - Batch 1: Stories with zero dependencies (can all start simultaneously)
- - Batch 2: Stories whose only dependencies are in Batch 1
- - Batch N: Stories whose dependencies are all in earlier batches
+ 2. Group items into parallel batches:
+ - Batch 1: Items with zero dependencies (can all start simultaneously)
+ - Batch 2: Items whose only dependencies are in Batch 1
+ - Batch N: Items whose dependencies are all in earlier batches
3. Within each batch, order by:
- - Number of stories that depend on this one (more dependents = higher priority)
- - Story type: BE before FE within a batch (APIs must exist before frontends)
+ - Number of items that depend on this one (more dependents = higher priority)
+ - Item type: BE/INFRA before FE within a batch (APIs must exist before frontends)
+ - Complexity: smaller items first within equal priority (unblock faster)
4. Calculate the critical path (longest chain of sequential dependencies).
+ 5. Estimate time per batch based on item complexity:
+ - S = 2h, M = 4h, L = 8h, XL = 16h
+ - Batch time = max(item times) assuming full parallelism within batch
+ - Total time = sum(batch times) along critical path
============================================================
OUTPUT
============================================================
## Dependency Map
- ### Stories Analyzed: {N}
+ ### Items Analyzed: {N}
+ **Input type:** {Stories / Code Modules / Mixed}
- ### Dependency Graph
+ ### Dependency Graph (ASCII)
```
{ASCII visualization}
Example:
- STORY-001 (BE: Auth) ─┬─► STORY-003 (BE: Users)
- └─► STORY-004 (BE: Orgs)
- STORY-002 (BE: Base) ────► STORY-005 (BE: Points)
- STORY-003 ───────────────► STORY-007 (FE: User Profile)
- STORY-004 ───────────────► STORY-008 (FE: Org Dashboard)
+ STORY-001 (BE: Auth) ---+---> STORY-003 (BE: Users)
+ +---> STORY-004 (BE: Orgs)
+ STORY-002 (BE: Base) -------> STORY-005 (BE: Points)
+ STORY-003 ------------------> STORY-007 (FE: User Profile)
+ STORY-004 ------------------> STORY-008 (FE: Org Dashboard)
```
+ ### Dependency Graph (Mermaid)
+ ```mermaid
+ graph TD
+ A[STORY-001: Auth] --> C[STORY-003: Users]
+ A --> D[STORY-004: Orgs]
+ B[STORY-002: Base] --> E[STORY-005: Points]
+ C --> G[STORY-007: User Profile]
+ D --> H[STORY-008: Org Dashboard]
+ ```
+
### Issues
- | Severity | Issue | Stories | Recommendation |
+ | Severity | Issue | Items | Recommendation |
|---|---|---|---|
- | {CRITICAL/WARN/INFO} | {issue type} | {story IDs} | {how to fix} |
+ | {CRITICAL/WARN/INFO} | {issue type} | {item IDs} | {specific fix — code-level for cycles} |
### Implementation Order
- **Batch 1** (no dependencies — start all in parallel):
- | # | Story | Type | Dependents | Notes |
- |---|---|---|---|---|
- | 1 | {story} | {BE/FE} | {N stories depend on this} | {notes} |
+ **Batch 1** (no dependencies — start all in parallel) — Est. {N}h:
+ | # | Item | Type | Size | Dependents | Notes |
+ |---|---|---|---|---|---|
+ | 1 | {item} | {BE/FE/INFRA} | {S/M/L/XL} | {N items depend on this} | {notes} |
- **Batch 2** (depends on Batch 1):
- | # | Story | Type | Blocked By | Notes |
- |---|---|---|---|---|
- | 1 | {story} | {BE/FE} | {story IDs} | {notes} |
+ **Batch 2** (depends on Batch 1) — Est. {N}h:
+ | # | Item | Type | Size | Blocked By | Notes |
+ |---|---|---|---|---|---|
+ | 1 | {item} | {BE/FE/INFRA} | {S/M/L/XL} | {item IDs} | {notes} |
... (repeat for each batch)
### Critical Path
```
{longest sequential chain}
- STORY-001 → STORY-003 → STORY-007 → STORY-010
+ STORY-001 (2h) -> STORY-003 (4h) -> STORY-007 (8h) -> STORY-010 (4h)
```
- - **Length:** {N} sequential stories
- - **Parallelizable stories:** {N} (across all batches)
- - **Max parallelism:** Batch {N} has {M} stories that can run simultaneously
+ - **Length:** {N} sequential items
+ - **Estimated critical path time:** {N}h
+ - **Parallelizable items:** {N} (across all batches)
+ - **Max parallelism:** Batch {N} has {M} items that can run simultaneously
+ ### Cycle-Breaking Recommendations
+ (Only if cycles were detected)
+ For each cycle:
+ 1. **Cycle:** A -> B -> C -> A
+ 2. **Root cause:** {why the cycle exists}
+ 3. **Recommended fix:** {specific action}
+ - For code: "Extract `SharedTypes` interface from `module_a.ts` and `module_b.ts` into `types/shared.ts`. Both modules import from the new file instead of each other."
+ - For stories: "Split STORY-003 into STORY-003a (schema only) and STORY-003b (logic). STORY-001 depends on 003a, 003b depends on 001."
+
### Summary
- - **Total stories:** {N}
+ - **Total items:** {N}
- **Batches:** {N}
- - **Critical path length:** {N} stories
- - **Max stories in parallel:** {N}
+ - **Critical path length:** {N} items ({N}h estimated)
+ - **Total estimated time (parallel):** {N}h (with full parallelism per batch)
+ - **Total estimated time (sequential):** {N}h (if done one at a time)
+ - **Max items in parallel:** {N}
- **Circular dependencies:** {N found / none}
-
- NEXT STEPS:
- - "Run `/review-implement {story}` starting from Batch 1."
- - "Run `/iterate` to build a batch of stories autonomously."
- - "Run `/arch-review {story}` on critical-path stories first."
+ - **High-risk items:** {list items with fan-in >= 5}