Surface hidden complexity, risks, dependencies, and likely project blow-up points in a proposed design or architecture. Use this when you have architecture docs, design proposals, or technical specs and need to identify where operational, cost, networking, or implementation complexity is hiding before committing resources. Produces a Complexity Heat Map and Hidden Risk Summary with source-anchored evidence and severity ratings. Ask for a "complexity map", "hidden risk analysis", "blow-up point review", or "complexity audit" to trigger this workflow.
How this skill is triggered — by the user, by Claude, or both
Slash command
/systems-thinking-plugin:complexity-mapperThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use Complexity Mapper when:
Use Complexity Mapper when:
Do not use Complexity Mapper when:
architecture-risk-review instead.context-sharding first, then feed sharded outputs into this workflow.| Input | Required | Description |
|---|---|---|
| Documentation | Yes | Architecture docs, design proposals, technical specs, API references, infrastructure diagrams, or any material describing the system under analysis. |
| Design assumptions | Yes | Stated or implied assumptions the design relies on — scaling expectations, cost models, SLA targets, team capacity. |
| Constraints | Yes | Hard limits: budget ceilings, latency requirements, compliance mandates, vendor lock-in boundaries. |
| Operational context | No | Current operational environment: existing infrastructure, team expertise, monitoring capabilities, incident history. Improves analysis quality significantly when provided. |
Before starting extraction, check reference/vendor_docs/ for pre-loaded vendor documentation relevant to the analysis target (e.g., service limits, pricing pages, known issues). Include any relevant vendor docs alongside user-provided materials as additional input for the doc-indexer.
Run the doc-indexer agent on all provided documentation to produce a structural map of the material:
The doc-indexer output serves as the routing table for Step 2. If the doc-indexer identifies significant gaps in the documentation, flag these immediately — they are themselves a complexity signal.
If the analysis requires external documentation (vendor docs, pricing pages, service quotas) that is not available locally, or if the doc-indexer identifies gaps that need external sources:
web-researcher agent with the specific topics or documentation gaps to research.Skip this step if all necessary material is already available locally or has been provided by the user.
Run the extraction-planner agent with the doc-indexer output (and any web-researcher Source Manifest from Step 1.5). The extraction-planner:
This step prevents extractor overload. Instead of one massive extraction prompt, each agent receives bounded, focused instructions.
Skip this step if the doc-indexer identifies ≤5 total sections. In that case, proceed directly to Step 3 with a single extractor per type.
Following the Dispatch Plan from Step 2 (or using default single-extractor-per-type if Step 2 was skipped), launch the extraction agents in parallel:
Agent A — caveat-extractor
Agent B — cost-capacity-analyst
Agent C — architecture-dependency-mapper
Gather outputs from all three extraction agents. For each output:
Pass all three extraction outputs plus the original design assumptions and constraints to the synthesis-brief-writer agent with instructions to produce:
Complexity Heat Map: A structured view of where complexity concentrates in the design, rated by:
Hidden Risk Summary: A prioritized list of risks that are not obvious from a surface reading of the design, including:
After synthesis, compare the output format and depth against any examples in reference/examples/ to ensure consistency with established quality standards.
Deliver the Complexity Heat Map and Hidden Risk Summary with:
The output consists of two artifacts conforming to their respective output contracts:
## Complexity Heat Map
### Summary
[1-2 sentence overview of where complexity concentrates]
### Heat Map
| Area | Complexity Type | Likelihood | Impact | Visibility | Source |
|---|---|---|---|---|---|
| [Component/Integration] | [Operational/Cost/Dependency/Implementation] | [H/M/L] | [H/M/L] | [Visible/Hidden/Unknown] | [Doc section ref] |
### Top Concentrations
1. [Area]: [Why this is the highest-risk complexity concentration]
2. [Area]: [Why this ranks second]
3. [Area]: [Why this ranks third]
## Hidden Risk Summary
### Risks (Ordered by Severity)
#### Risk: [Name]
- **Trigger**: [What causes this risk to materialize]
- **Evidence**: [Specific findings from extraction, with source anchors]
- **Threatened Assumptions**: [Which design assumptions this undermines]
- **Severity**: [Critical / High / Medium / Low]
- **Confidence**: [High / Medium / Low — based on evidence quality]
- **Recommended Action**: [Investigate / Prototype / Get vendor confirmation / Redesign]
[Repeat for each risk]
### Evidence Gaps
- [Topic]: [What is missing and why it matters]
### Recommended Next Steps
1. [Action with rationale]
2. [Action with rationale]
| Failure Mode | Signal | Response |
|---|---|---|
| Insufficient documentation | doc-indexer identifies major structural gaps; extraction agents return thin results | Flag low confidence on the overall analysis. List specific documentation gaps as findings in their own right. Recommend the user provide additional material before treating the analysis as comprehensive. |
| Single-source analysis | Most findings come from one document or one extraction agent | Flag in the output that findings are single-source. Confidence ratings should be lowered accordingly. Recommend cross-referencing with additional sources. |
| Design too early-stage | Provided materials are aspirational rather than concrete; extraction agents cannot identify specific components or dependencies | Stop or downgrade the analysis. Inform the user that complexity mapping requires concrete design artifacts. Recommend returning after the design has been elaborated. |
| Extraction agent contradiction | cost-capacity-analyst and caveat-extractor produce conflicting assessments of the same component | Surface the contradiction explicitly in the synthesis. Do not silently resolve it. Present both perspectives and recommend investigation. |
| Scope too large for single pass | doc-indexer produces a structural map with more than 30 distinct sections or 5+ major subsystems | Recommend running context-sharding first to split the material, then running complexity-mapper on each shard, followed by a cross-shard synthesis pass. |
npx claudepluginhub fakoli/systems-thinking-plugin --plugin systems-thinking-pluginPerforms systematic architecture reviews across 7 dimensions (structural, scalability, enterprise readiness, performance, security, ops, data) with scored reports and prioritized recommendations.
Reverse-engineers existing projects to produce auto-anchored Design Docs, API contracts, and Threat Models from real code, IaC, and observability data.
Enriches /ctx-architecture artifacts with GitNexus MCP data: verifies blast radius, execution flows, domain clustering, registration sites. Run after base architecture analysis for quantification.