dep-map

name	dep-map
description	Maps dependencies between stories, code modules, tickets, or specs. Computes optimal implementation order with parallel batches, cycle detection, and critical path analysis.
version	2.0.0
category	analysis
platforms	["CLAUDE_CODE"]

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 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 0: DETECT INPUT TYPE

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 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 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 Stories / Specs

For each item pair (A, B), check for dependencies:

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.

For Code Modules

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: { itemId: [depends_on_ids] }

============================================================ PHASE 3: DETECT ISSUES

1. Circular dependencies: Run cycle detection on the graph. 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: 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 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 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 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 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

============================================================ SELF-HEALING VALIDATION (max 2 iterations)

After producing output, validate data quality and completeness:

1. Verify all output sections have substantive content (not just headers).
2. Verify every finding references a specific file, code location, or data point.
3. Verify recommendations are actionable and evidence-based.
4. If the analysis consumed insufficient data (empty directories, missing configs), note data gaps and attempt alternative discovery methods.

IF VALIDATION FAILS:

• Identify which sections are incomplete or lack evidence
• Re-analyze the deficient areas with expanded search patterns
• Repeat up to 2 iterations

IF STILL INCOMPLETE after 2 iterations:

• Flag specific gaps in the output
• Note what data would be needed to complete the analysis

============================================================ OUTPUT

Dependency Map

Items Analyzed: {N}

Input type: {Stories / Code Modules / Mixed}

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)

Dependency Graph (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	Items	Recommendation
{CRITICAL/WARN/INFO}	{issue type}	{item IDs}	{specific fix — code-level for cycles}

Implementation Order

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) — 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 (2h) -> STORY-003 (4h) -> STORY-007 (8h) -> STORY-010 (4h)

• 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 items: {N}
• Batches: {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}
• High-risk items: {list items with fan-in >= 5}

============================================================ SELF-EVOLUTION TELEMETRY

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /dep-map — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.