Initial commit

2025-11-30 08:38:26 +08:00
commit 41d9f6b189
304 changed files with 98322 additions and 0 deletions
--- a/skills/mapping-visualization-scaffolds/SKILL.md
+++ b/skills/mapping-visualization-scaffolds/SKILL.md
@@ -0,0 +1,178 @@
+---
+name: mapping-visualization-scaffolds
+description: Use when complex systems need visual documentation, mapping component relationships and dependencies, creating hierarchies or taxonomies, documenting process flows or decision trees, understanding system architectures, visualizing data lineage or knowledge structures, planning information architecture, or when user mentions concept maps, system diagrams, dependency mapping, relationship visualization, or architecture blueprints.
+---
+
+# Mapping & Visualization Scaffolds
+
+## Table of Contents
+- [Purpose](#purpose)
+- [When to Use](#when-to-use)
+- [What Is It](#what-is-it)
+- [Workflow](#workflow)
+- [Common Patterns](#common-patterns)
+- [Guardrails](#guardrails)
+- [Quick Reference](#quick-reference)
+
+## Purpose
+
+Create visual maps that make implicit relationships, dependencies, and structures explicit through diagrams, concept maps, and architectural blueprints.
+
+## When to Use
+
+Use mapping-visualization-scaffolds when you need to:
+
+**System Understanding:**
+- Document complex system architectures (microservices, infrastructure, data flows)
+- Map component dependencies and relationships
+- Visualize API endpoints and integration points
+- Understand legacy system structure
+
+**Knowledge Organization:**
+- Create concept maps for learning or teaching
+- Build taxonomies and hierarchies
+- Organize research literature or domain knowledge
+- Structure information architecture
+
+**Process & Flow Documentation:**
+- Map user journeys and workflows
+- Create decision trees and flowcharts
+- Document approval chains or escalation paths
+- Visualize project dependencies and timelines
+
+**Strategic Visualization:**
+- Map stakeholder relationships and influence
+- Visualize organizational structures
+- Create competitive landscape maps
+- Document value chains or business models
+
+## What Is It
+
+A mapping scaffold is a structured approach to creating visual representations that show:
+- **Nodes** (components, concepts, people, steps)
+- **Relationships** (connections, dependencies, hierarchies, flows)
+- **Attributes** (properties, states, metadata)
+- **Groupings** (clusters, categories, layers)
+
+**Quick Example:**
+
+For a microservices architecture:
+```
+Nodes: API Gateway, Auth Service, User Service, Payment Service, Database
+Relationships:
+  - API Gateway → calls → Auth Service
+  - Auth Service → validates → User Service
+  - Payment Service → reads/writes → Database
+Groupings: Frontend Layer, Business Logic Layer, Data Layer
+```
+
+This creates a visual map showing how services connect and depend on each other.
+
+## Workflow
+
+Copy this checklist and track your progress:
+
+```
+Mapping Visualization Progress:
+- [ ] Step 1: Clarify mapping purpose
+- [ ] Step 2: Identify nodes and relationships
+- [ ] Step 3: Choose visualization approach
+- [ ] Step 4: Create the map
+- [ ] Step 5: Validate and refine
+```
+
+**Step 1: Clarify mapping purpose**
+
+Ask user about their goal: What system/concept needs mapping? Who's the audience? What decisions will this inform? What level of detail is needed? See [Common Patterns](#common-patterns) for typical use cases.
+
+**Step 2: Identify nodes and relationships**
+
+List all key elements (nodes) and their connections (relationships). Identify hierarchy levels, dependency types, and grouping criteria. For simple cases (< 20 nodes), use [resources/template.md](resources/template.md). For complex systems (50+ nodes) or collaborative sessions, see [resources/methodology.md](resources/methodology.md) for advanced strategies.
+
+**Step 3: Choose visualization approach**
+
+Select format based on complexity: Simple lists for < 10 nodes, tree diagrams for hierarchies, network graphs for complex relationships, or layered diagrams for systems. For large-scale systems or multi-map hierarchies, consult [resources/methodology.md](resources/methodology.md) for mapping strategies and tool selection. See [Common Patterns](#common-patterns) for guidance.
+
+**Step 4: Create the map**
+
+Build the visualization using markdown, ASCII diagrams, or structured text. Start with high-level structure, then add details. Include legend if needed. Use [resources/template.md](resources/template.md) as your scaffold.
+
+**Step 5: Validate and refine**
+
+Check completeness, clarity, and accuracy using [resources/evaluators/rubric_mapping_visualization_scaffolds.json](resources/evaluators/rubric_mapping_visualization_scaffolds.json). Ensure all critical nodes and relationships are present. Minimum standard: Score ≥ 3.5 average.
+
+## Common Patterns
+
+**Architecture Diagrams:**
+- System components as nodes
+- Service calls/data flows as relationships
+- Layers as groupings (frontend, backend, data)
+- Use for: Technical documentation, system design reviews
+
+**Concept Maps:**
+- Concepts/ideas as nodes
+- "is-a", "has-a", "leads-to" as relationships
+- Themes as groupings
+- Use for: Learning, knowledge organization, research synthesis
+
+**Dependency Graphs:**
+- Tasks/features/modules as nodes
+- "depends-on", "blocks", "requires" as relationships
+- Phases/sprints as groupings
+- Use for: Project planning, risk assessment, parallel work identification
+
+**Hierarchies & Taxonomies:**
+- Categories/classes as nodes
+- Parent-child relationships
+- Levels as groupings (L1, L2, L3)
+- Use for: Information architecture, org charts, skill trees
+
+**Flow Diagrams:**
+- Steps/states as nodes
+- Transitions/decisions as relationships
+- Swim lanes as groupings (roles, systems)
+- Use for: Process documentation, user journeys, decision trees
+
+## Guardrails
+
+**Scope Management:**
+- Focus on relationships that matter for the specific purpose
+- Don't map everything—map what's decision-relevant
+- Stop at appropriate detail level (usually 3-4 layers deep)
+- For systems with > 50 nodes, create multiple focused maps
+
+**Clarity Over Completeness:**
+- Prioritize understandability over exhaustiveness
+- Use consistent notation and naming
+- Add legend if > 3 relationship types
+- Group related nodes to reduce visual complexity
+
+**Validation:**
+- Verify accuracy with subject matter experts
+- Test if someone unfamiliar can understand the map
+- Check for missing critical relationships
+- Ensure directionality is clear (A → B vs A ← B)
+
+**Common Pitfalls:**
+- ❌ Creating "hairball" diagrams with too many connections
+- ❌ Mixing abstraction levels (strategic + implementation details)
+- ❌ Using inconsistent node/relationship representations
+- ❌ Forgetting to state the map's purpose and scope
+
+## Quick Reference
+
+**Resources:**
+- `resources/template.md` - Structured scaffold for creating maps
+- `resources/evaluators/rubric_mapping_visualization_scaffolds.json` - Quality criteria
+
+**Output:**
+- File: `mapping-visualization-scaffolds.md` in current directory
+- Contains: Nodes, relationships, groupings, legend (if needed)
+- Format: Markdown with ASCII diagrams or structured lists
+
+**Success Criteria:**
+- All critical nodes identified
+- Relationships clearly labeled with directionality
+- Appropriate grouping/layering applied
+- Understandable by target audience without explanation
+- Validated against quality rubric (score ≥ 3.5)
--- a/skills/mapping-visualization-scaffolds/resources/evaluators/rubric_mapping_visualization_scaffolds.json
+++ b/skills/mapping-visualization-scaffolds/resources/evaluators/rubric_mapping_visualization_scaffolds.json
@@ -0,0 +1,128 @@
+{
+  "criteria": [
+    {
+      "name": "Completeness",
+      "description": "All critical nodes and relationships are identified and documented",
+      "levels": {
+        "5": "All critical nodes present, all significant relationships documented, appropriate groupings/layers defined, legend provided if needed, metadata complete",
+        "4": "Most critical nodes and relationships present, minor gaps in groupings or metadata, legend present if needed",
+        "3": "Key nodes and relationships present but some secondary elements missing, groupings incomplete, metadata partially complete",
+        "2": "Several critical nodes or relationships missing, groupings absent or unclear, metadata sparse",
+        "1": "Major gaps in nodes/relationships, no groupings, minimal or no metadata"
+      }
+    },
+    {
+      "name": "Clarity",
+      "description": "The visualization is understandable, well-organized, and uses consistent notation",
+      "levels": {
+        "5": "Crystal clear visualization, consistent naming/notation throughout, logical organization, no ambiguity in relationships, directionality explicit",
+        "4": "Clear visualization with minor inconsistencies, mostly logical organization, directionality usually clear",
+        "3": "Generally clear but some confusing elements, some notation inconsistencies, directionality sometimes ambiguous",
+        "2": "Difficult to follow in places, inconsistent notation, unclear directionality, poor organization",
+        "1": "Confusing or incomprehensible, no clear notation system, directionality absent"
+      }
+    },
+    {
+      "name": "Accuracy",
+      "description": "Relationships and dependencies are correctly identified and represented",
+      "levels": {
+        "5": "All relationships accurately represent reality, correct directionality, relationship types properly labeled, no errors",
+        "4": "Relationships mostly accurate, minor errors in directionality or labeling, types generally correct",
+        "3": "Some inaccurate relationships, occasional errors in directionality, relationship types sometimes incorrect",
+        "2": "Multiple inaccurate relationships, frequent errors, relationship types often wrong",
+        "1": "Many inaccurate or incorrect relationships, unreliable representation"
+      }
+    },
+    {
+      "name": "Format Appropriateness",
+      "description": "The chosen visualization format matches the complexity and nature of the system",
+      "levels": {
+        "5": "Perfect format choice for the relationship patterns, complexity level appropriate, scalable structure, right level of detail",
+        "4": "Good format choice with minor suboptimal aspects, generally appropriate complexity and detail",
+        "3": "Acceptable format but could be better, some mismatch between format and content, detail level inconsistent",
+        "2": "Poor format choice for the content, significant mismatch, wrong complexity level, inappropriate detail",
+        "1": "Completely inappropriate format, impossible to follow, wrong complexity level"
+      }
+    },
+    {
+      "name": "Scoping",
+      "description": "Clear boundaries defined, appropriate level of detail, purpose explicitly stated",
+      "levels": {
+        "5": "Clear purpose statement, explicit scope boundaries (what's in/out), appropriate detail level for audience, constraints stated",
+        "4": "Purpose stated, scope mostly clear, generally appropriate detail level, most constraints noted",
+        "3": "Purpose vague or implicit, scope somewhat unclear, detail level sometimes inappropriate, few constraints stated",
+        "2": "Purpose unclear, scope poorly defined, detail level often wrong, constraints not stated",
+        "1": "No clear purpose, undefined scope, inappropriate detail level, no constraints"
+      }
+    },
+    {
+      "name": "Visual Organization",
+      "description": "Layout facilitates understanding, uses grouping effectively, avoids visual clutter",
+      "levels": {
+        "5": "Excellent layout, effective use of grouping/layering, clean visual hierarchy, no 'hairball' effect, scannable at a glance",
+        "4": "Good layout with minor issues, grouping mostly effective, generally scannable, minimal clutter",
+        "3": "Acceptable layout but could improve, grouping present but weak, somewhat cluttered, harder to scan",
+        "2": "Poor layout, ineffective grouping, cluttered visualization, difficult to scan, confusing structure",
+        "1": "Chaotic layout, no effective grouping, severe clutter, impossible to scan, no structure"
+      }
+    },
+    {
+      "name": "Actionability",
+      "description": "The map enables decisions, understanding, or actions based on insights",
+      "levels": {
+        "5": "Clearly enables specific decisions/actions, insights explicitly highlighted, critical paths/bottlenecks identified, recommendations provided",
+        "4": "Enables decisions with some interpretation, key insights noted, some critical elements highlighted",
+        "3": "Somewhat useful for decisions but requires significant interpretation, few insights noted, limited highlighting",
+        "2": "Difficult to derive actions from the map, insights not highlighted, unclear what to do with it",
+        "1": "Provides no actionable value, no insights, unclear purpose or application"
+      }
+    },
+    {
+      "name": "Documentation Quality",
+      "description": "Adequate descriptions, legend provided if needed, assumptions/limitations stated",
+      "levels": {
+        "5": "Comprehensive node/relationship descriptions, legend present if >3 types, assumptions stated, limitations noted, insights documented",
+        "4": "Good descriptions, legend present if needed, most assumptions stated, some limitations noted",
+        "3": "Basic descriptions, legend missing when needed, few assumptions stated, limitations not noted",
+        "2": "Sparse descriptions, no legend when needed, assumptions not stated, no limitations noted",
+        "1": "Minimal or no descriptions, no legend, no documentation of assumptions or limitations"
+      }
+    }
+  ],
+  "scale": 5,
+  "passing_threshold": 3.5,
+  "scoring_guidance": {
+    "overall_minimum": "Average score must be ≥ 3.5 across all criteria",
+    "critical_criteria": [
+      "Completeness",
+      "Accuracy",
+      "Clarity"
+    ],
+    "critical_threshold": "Critical criteria must each be ≥ 3.0 (even if average is ≥ 3.5)",
+    "improvement_priority": "If below threshold, prioritize improvements in order: Completeness → Accuracy → Clarity → Format Appropriateness → others"
+  },
+  "common_failure_modes": [
+    "Too many nodes (>50) without splitting into multiple focused maps",
+    "Hairball diagram with crossing lines and unclear relationships",
+    "Inconsistent notation or naming conventions",
+    "Missing critical dependencies or relationships",
+    "Wrong format choice (e.g., tree diagram for network, list for complex graph)",
+    "No grouping/layering for complex systems (>20 nodes)",
+    "Ambiguous directionality (unclear which way relationships flow)",
+    "No legend when multiple relationship types present",
+    "Mixing abstraction levels in single map",
+    "Undefined scope or purpose"
+  ],
+  "excellence_indicators": [
+    "Target audience can understand without explanation",
+    "Critical paths or bottlenecks visually highlighted",
+    "Appropriate grouping reduces visual complexity",
+    "Consistent notation throughout",
+    "Clear purpose and scope stated upfront",
+    "Insights section highlights key findings",
+    "Multiple visualization formats considered, best one chosen",
+    "Scalable structure (can add nodes without breaking layout)",
+    "Validation with stakeholders or SMEs completed",
+    "Legend present when needed, absent when not"
+  ]
+}
--- a/skills/mapping-visualization-scaffolds/resources/methodology.md
+++ b/skills/mapping-visualization-scaffolds/resources/methodology.md
@@ -0,0 +1,491 @@
+# Advanced Mapping & Visualization Methodology
+
+## Workflow
+
+Copy this checklist and track your progress:
+
+```
+Advanced Mapping Progress:
+- [ ] Step 1: Assess complexity and scope
+- [ ] Step 2: Choose mapping strategy
+- [ ] Step 3: Select tools and formats
+- [ ] Step 4: Execute mapping process
+- [ ] Step 5: Validate with stakeholders
+- [ ] Step 6: Iterate and refine
+```
+
+**Step 1: Assess complexity and scope**
+
+Evaluate system size (nodes/relationships), stakeholder diversity, and update frequency. See [1. Complexity Assessment](#1-complexity-assessment) for decision criteria on when advanced techniques are needed.
+
+**Step 2: Choose mapping strategy**
+
+Select from single comprehensive map, multi-map hierarchy, or modular view-based approach based on complexity. See [2. Mapping Strategies for Scale](#2-mapping-strategies-for-scale) for guidance.
+
+**Step 3: Select tools and formats**
+
+Choose between manual (text/markdown), semi-automated (Mermaid), or visual tools (draw.io, GraphViz) based on collaboration needs and update frequency. See [3. Tool Selection](#3-tool-selection) for criteria.
+
+**Step 4: Execute mapping process**
+
+Apply chosen strategy using collaborative or individual workflows. See [4. Execution Patterns](#4-execution-patterns) for facilitation techniques and [5. Advanced Layout Techniques](#5-advanced-layout-techniques) for optimization.
+
+**Step 5: Validate with stakeholders**
+
+Conduct structured review sessions using [6. Validation Approaches](#6-validation-approaches) to ensure accuracy and completeness.
+
+**Step 6: Iterate and refine**
+
+Incorporate feedback and maintain maps over time using [7. Maintenance and Evolution](#7-maintenance-and-evolution) patterns.
+
+---
+
+## 1. Complexity Assessment
+
+Use this framework to determine if advanced methodology is needed:
+
+### Simple Case (Use template.md)
+- **Nodes**: < 20
+- **Relationships**: Mostly one type
+- **Stakeholders**: 1-2 people
+- **Change frequency**: One-time or rare
+- **Structure**: Clear hierarchy or simple network
+→ **Action**: Follow [template.md](template.md), use Simple List or Tree format
+
+### Moderate Case (Consider this methodology)
+- **Nodes**: 20-50
+- **Relationships**: 2-4 types
+- **Stakeholders**: 3-8 people
+- **Change frequency**: Quarterly updates
+- **Structure**: Some cross-dependencies, multiple layers
+→ **Action**: Use this methodology, focus on [Multi-Map Hierarchy](#multi-map-hierarchy)
+
+### Complex Case (Definitely use this methodology)
+- **Nodes**: 50-200+
+- **Relationships**: 5+ types, bidirectional
+- **Stakeholders**: 10+ people across teams/orgs
+- **Change frequency**: Continuous evolution
+- **Structure**: Dense interconnections, emergent properties
+→ **Action**: Use this methodology, apply [Modular View-Based](#modular-view-based-approach) approach
+
+### Signals You Need Advanced Techniques
+- Creating "hairball" diagrams with crossing edges everywhere
+- Stakeholders can't find relevant information in map
+- Map becomes outdated within weeks
+- Multiple teams need different views of same system
+- Need to show evolution over time
+- System has 100+ nodes that can't be easily decomposed
+
+---
+
+## 2. Mapping Strategies for Scale
+
+### Single Comprehensive Map
+
+**When to use:**
+- 20-50 nodes maximum
+- Single primary use case
+- Stable system (low change rate)
+- Uniform stakeholder audience
+
+**Techniques:**
+- Use aggressive grouping/layering to reduce visual complexity
+- Apply color coding consistently (by type, criticality, ownership)
+- Maximize whitespace between groups
+- Create clear visual hierarchy (size, position, color)
+
+**Example structure:**
+```
+┌─── Frontend Layer ────────────────────┐
+│  UI Components (N1-N5)                │
+│  State Management (N6-N8)             │
+└───────────────────────────────────────┘
+            ↓ API calls
+┌─── Backend Layer ─────────────────────┐
+│  Services (N9-N15)                    │
+│  Business Logic (N16-N20)             │
+└───────────────────────────────────────┘
+            ↓ queries
+┌─── Data Layer ────────────────────────┐
+│  Databases (N21-N25)                  │
+└───────────────────────────────────────┘
+```
+
+### Multi-Map Hierarchy
+
+**When to use:**
+- 50-150 nodes
+- Multiple abstraction levels needed
+- Different audiences need different detail
+- System has natural subsystem boundaries
+
+**Structure:**
+1. **L0 Overview Map** (5-15 nodes): High-level components only
+2. **L1 Subsystem Maps** (10-30 nodes each): Detail within each component
+3. **L2 Detail Maps** (optional): Deep dive into complex subsystems
+
+**Linking approach:**
+- Each L0 node links to its L1 detail map
+- Use consistent naming: `system-overview.md`, `system-auth-subsystem.md`, `system-payment-subsystem.md`
+- Include navigation breadcrumbs in each map
+
+**Example hierarchy:**
+```
+L0: E-commerce Platform Overview
+├─ Frontend (5 nodes) → L1: frontend-detail.md
+├─ API Gateway (3 nodes) → L1: api-gateway-detail.md
+├─ Auth Service (4 nodes) → L1: auth-service-detail.md
+│  └─ JWT Module → L2: auth-jwt-detail.md
+├─ Product Service (8 nodes) → L1: product-service-detail.md
+├─ Payment Service (6 nodes) → L1: payment-service-detail.md
+└─ Data Layer (4 nodes) → L1: data-layer-detail.md
+```
+
+### Modular View-Based Approach
+
+**When to use:**
+- 100+ nodes
+- Multiple stakeholder groups with different concerns
+- Need to show different perspectives of same system
+- High change frequency
+
+**View types:**
+- **Structural view**: What components exist and how they're organized
+- **Dependency view**: What depends on what (for deployment planning)
+- **Data flow view**: How data moves through system
+- **Security view**: Trust boundaries, authentication flows
+- **Operational view**: Monitoring, alerting, ownership
+
+**Approach:**
+1. Maintain single **master node/relationship database** (spreadsheet or JSON)
+2. Generate **filtered views** for specific audiences/purposes
+3. Each view shows subset of nodes/relationships relevant to that concern
+4. Cross-reference between views using node IDs
+
+**Example - same system, different views:**
+
+**View 1: Engineering Deployment Dependencies**
+```
+Shows: All services, databases, external APIs
+Relationships: depends-on, requires, blocks
+Purpose: Determine deployment order, identify risks
+```
+
+**View 2: Product Manager Feature Map**
+```
+Shows: User-facing features, backend services supporting them
+Relationships: enables, requires, affects
+Purpose: Understand feature scope, plan releases
+```
+
+**View 3: Security Boundaries**
+```
+Shows: Services, trust zones, auth components
+Relationships: trusts, authenticates, authorizes
+Purpose: Threat modeling, compliance review
+```
+
+---
+
+## 3. Tool Selection
+
+### Tool Selection Guide
+
+**Text/Markdown:** Quick docs, frequent updates, < 20 nodes, version control critical
+**Mermaid:** 20-40 nodes, markdown integration, flowcharts, version control
+**Draw.io:** 40+ nodes, visual quality matters, presentations, collaborative editing
+**GraphViz:** Automatic layout, 100+ nodes, programmatic generation
+**Specialized (Lucidchart, etc):** Enterprise collaboration, executive presentations, branded templates
+
+---
+
+## 4. Execution Patterns
+
+### Solo Mapping Workflow
+
+**5-step process for 30-50 node maps (70-120 min total):**
+
+1. **Brain dump** (15-30 min): List all nodes without structure, aim for exhaustiveness
+2. **Cluster** (10-15 min): Group related nodes, identify subsystems/themes
+3. **Structure** (20-40 min): Choose format, define relationships, create layers
+4. **Refine** (15-20 min): Add missing nodes, remove redundancy, clarify relationships
+5. **Validate** (10-15 min): Self-check with [rubric](evaluators/rubric_mapping_visualization_scaffolds.json), test understanding
+
+### Collaborative Mapping Workshop
+
+**5-phase process for 2-8 participants (80 min total):**
+
+1. **Setup** (5 min): State purpose/scope, show example, assign roles (Facilitator, Scribe, Timekeeper)
+2. **Individual brainstorm** (10 min): Each person lists 15-20 nodes on sticky notes, no discussion
+3. **Share and cluster** (20 min): Share nodes (2 min each), group similar, merge duplicates, name clusters
+4. **Relationship mapping** (20 min): Draw key relationships, use colors for types, vote on disputed connections
+5. **Structure and refine** (15 min): Choose format together, assign digital creation, document parking lot
+6. **Review and validate** (10 min): Walk through map, identify gaps, assign follow-up owners
+
+**Facilitation tips:** Round-robin participation, park tangents, enforce timeboxes, capture dissent explicitly
+
+---
+
+## 5. Advanced Layout Techniques
+
+### Minimizing Edge Crossings
+
+**Problem:** Complex graphs become "hairballs" with edges crossing everywhere.
+
+**Solutions:**
+
+1. **Layered approach** (works for hierarchies)
+   - Assign nodes to horizontal layers (L1, L2, L3)
+   - Minimize crossings between adjacent layers
+   - Use dummy nodes for long-distance edges
+
+2. **Force-directed layout** (works for networks)
+   - Related nodes pull together
+   - Unrelated nodes push apart
+   - Let GraphViz or similar tool calculate
+
+3. **Manual optimization**
+   - Place highly-connected nodes centrally
+   - Group tightly-coupled nodes
+   - Use orthogonal routing (edges follow grid)
+
+4. **Split the map**
+   - If > 30 edge crossings, split into multiple maps
+   - One map per subsystem
+   - Create overview map showing subsystem relationships
+
+### Handling Bidirectional Relationships
+
+**Problem:** A ↔ B creates visual clutter with two arrows.
+
+**Solutions:**
+
+1. **Single line with double arrow**: `A ←→ B`
+2. **Annotate relationship**: `A ←[reads/writes]→ B`
+3. **Split by type**:
+   - Show `A → B` for "calls"
+   - Show `B → A` for "sends events"
+4. **Separate views**: One for each direction
+
+### Visual Hierarchy Patterns
+
+**Use visual weight to show importance:**
+
+```
+Size:
+  ┌────────────┐     ← Critical component (large)
+  │  Database  │
+  └────────────┘
+
+  ┌────────┐         ← Standard component (medium)
+  │ Service │
+  └────────┘
+
+  ┌────┐             ← Utility (small)
+  │Util│
+  └────┘
+
+Color/Style:
+  ██████ Core system (solid, dark)
+  ▓▓▓▓▓▓ Standard (solid, medium)
+  ░░░░░░ Optional (light/dotted)
+
+Position:
+  Top → High-level/strategic
+  Middle → Tactical
+  Bottom → Implementation details
+```
+
+---
+
+## 6. Validation Approaches
+
+### Structured Review Process
+
+**Step 1: Completeness check (5-10 min)**
+Ask reviewers:
+- "What critical components are missing?"
+- "What relationships are incorrect or missing?"
+- "What groupings don't make sense?"
+
+**Step 2: Accuracy verification (10-15 min)**
+For each subsystem:
+- Assign subject matter expert
+- Verify node descriptions
+- Validate relationship types and directionality
+- Confirm groupings
+
+**Step 3: Usability test (5 min)**
+Give map to someone unfamiliar:
+- Can they answer basic questions from the map?
+- "Which components depend on X?"
+- "What happens if Y fails?"
+- "Who owns component Z?"
+
+**Step 4: Scenario walkthrough (10-15 min)**
+Pick 3-5 scenarios:
+- "A user logs in" - trace through the map
+- "We deploy service X" - identify impacts
+- "Database Y goes down" - find affected components
+
+### Validation Metrics
+
+Track these across iterations:
+
+- **Coverage**: % of known components included
+- **Accuracy**: % of relationships verified by SMEs
+- **Usability**: # of correct answers in usability test
+- **Completeness**: # of gaps identified in reviews
+- **Consensus**: % of stakeholders agreeing on structure
+
+**Target thresholds:**
+- Coverage ≥ 95% (all critical + most secondary)
+- Accuracy ≥ 90% (verified by SMEs)
+- Usability ≥ 70% (most questions answered correctly)
+
+---
+
+## 7. Maintenance and Evolution
+
+### Update Strategies
+
+**Reactive (as-needed):**
+- Update when someone reports inaccuracy
+- Quarterly review cycle
+- Works for stable systems
+- **Risk**: Map becomes stale, people stop trusting it
+
+**Proactive (systematic):**
+- Assign ownership to specific people/teams
+- Integrate into change processes (new service → update map)
+- Automated checks (compare with service registry, org chart)
+- **Benefit**: Map stays current, becomes trusted resource
+
+### Version Control Patterns
+
+**For text-based maps (Markdown, Mermaid):**
+- Store in Git alongside code
+- Include map updates in PRs that change architecture
+- Use conventional commits: `docs(map): add new payment service`
+- Tag versions: `v1.0-system-map-2024Q4`
+
+**For visual tools (Draw.io, Lucidchart):**
+- Export to version control (XML, JSON) regularly
+- Maintain changelog in separate document
+- Create dated snapshots: `architecture-2024-11-12.drawio`
+
+### Dealing with Drift
+
+**Symptoms of map drift:**
+- Stakeholders reference outdated information
+- Multiple competing maps exist
+- Last update > 6 months ago
+- New team members don't use it
+
+**Recovery process:**
+1. **Audit current state** (1-2 days): Compare map to reality
+2. **Triage errors**: Critical fix (wrong), update (outdated), remove (obsolete)
+3. **Batch update session**: Fix all at once, not incrementally
+4. **Re-validate**: Get stakeholder sign-off
+5. **Establish maintenance**: Assign owners, set review cadence
+6. **Sunset old maps**: Archive competing/outdated versions
+
+---
+
+## 8. Domain-Specific Patterns
+
+### Software Architecture
+**Focus:** Service boundaries, data flows, deployment dependencies, scalability bottlenecks
+**Relationships:** `calls`, `publishes/subscribes`, `reads/writes`, `depends-on`
+**Layers:** Presentation (web/mobile/API), Application (services/logic), Data (databases/caches/queues)
+
+### Organizational Structure
+**Focus:** Reporting relationships, communication patterns, decision authority, ownership
+**Relationships:** `reports-to`, `collaborates-with`, `escalates-to`, `consults`
+**Groupings:** By function, product line, or location
+
+### Process/Workflow
+**Focus:** Step sequence, decision points, handoffs, bottlenecks
+**Relationships:** `leads-to`, `branches-on`, `requires-approval`, `escalates`
+**Formats:** Swimlane (multiple actors), decision tree (conditionals), linear flow
+
+---
+
+## 9. Troubleshooting Common Issues
+
+### Issue: Map is too cluttered
+
+**Symptoms:** Can't see structure, edges cross everywhere, hard to scan
+
+**Fixes:**
+1. Increase grouping - combine nodes into subsystems
+2. Split into multiple maps (overview + detail)
+3. Remove transitive relationships (if A→B→C, remove A→C)
+4. Use different views for different audiences
+
+### Issue: Stakeholders disagree on structure
+
+**Symptoms:** Debates about groupings, relationship directions, what's included
+
+**Fixes:**
+1. Document perspectives explicitly: "Engineering view shows X, Product view shows Y"
+2. Create view-specific maps rather than one "true" map
+3. Focus on agreed-upon core, mark disputed areas
+4. Use validation scenarios - test both structures
+
+### Issue: Map becomes outdated quickly
+
+**Symptoms:** Weekly corrections needed, people stop using it
+
+**Fixes:**
+1. Reduce scope - map stable core only
+2. Assign clear ownership and update process
+3. Automate where possible (generate from config files)
+4. Accept "directionally correct" vs "perfectly accurate"
+
+### Issue: Can't decide on visualization format
+
+**Symptoms:** Trying multiple formats, none feels right
+
+**Fixes:**
+1. Match format to relationship pattern:
+   - Hierarchy → Tree
+   - Network → Graph
+   - Sequence → Swimlane/Flow
+2. Create small prototype in each format (10 nodes)
+3. Test with stakeholder: "Which helps you understand better?"
+4. It's okay to use different formats for different subsystems
+
+---
+
+## 10. Success Patterns from Practice
+
+1. **Start messy, refine clean** - Brain dump first, organize later
+2. **Version with system** - Map updates = part of change process
+3. **Multiple maps > mega-map** - 5 focused maps beat 1 hairball
+4. **Show evolution** - Include roadmap/changelog views
+5. **Make navigable** - Links between maps, collapsible sections, filters
+6. **Visual conventions matter** - Document notation, consistency > perfection
+7. **Involve stakeholders early** - Collaborative mapping = shared understanding + buy-in
+8. **Test usability continuously** - If people can't answer questions, it's not useful
+
+---
+
+## When to Apply This Methodology
+
+Use this methodology if you're:
+
+✓ Mapping systems with 50+ nodes
+✓ Managing multiple stakeholder perspectives
+✓ Needing to maintain maps over time (not one-off)
+✓ Creating maps for diverse audiences (technical + non-technical)
+✓ Dealing with high system complexity or frequent change
+✓ Facilitating group mapping sessions
+✓ Generating maps programmatically from data
+✓ Building a "living documentation" practice
+
+Go back to [template.md](template.md) if you're:
+✗ Mapping simple systems (< 20 nodes)
+✗ Creating one-off documentation
+✗ Working alone with single audience
+✗ Time-constrained (need map in < 1 hour)
--- a/skills/mapping-visualization-scaffolds/resources/template.md
+++ b/skills/mapping-visualization-scaffolds/resources/template.md
@@ -0,0 +1,407 @@
+# Mapping & Visualization Scaffolds Template
+
+## Workflow
+
+Copy this checklist and track your progress:
+
+```
+Template Progress:
+- [ ] Step 1: Define map metadata
+- [ ] Step 2: List all nodes
+- [ ] Step 3: Define relationships
+- [ ] Step 4: Choose visualization format
+- [ ] Step 5: Create the visualization
+- [ ] Step 6: Add legend and insights
+```
+
+**Step 1: Define map metadata**
+
+Fill out the Map Metadata section in the Quick Template with title, purpose, audience, and scope. This ensures the map serves the right goal. See [Section Guidance - Map Metadata](#1-map-metadata) for details.
+
+**Step 2: List all nodes**
+
+Complete the Nodes section in the Quick Template with all key elements (components, concepts, entities). Include brief descriptions. See [Section Guidance - Nodes](#2-nodes) for what to include.
+
+**Step 3: Define relationships**
+
+Document the Relationships section in the Quick Template with connections between nodes. Specify type and directionality. See [Section Guidance - Relationships](#3-relationships) for relationship types.
+
+**Step 4: Choose visualization format**
+
+Select from [Visualization Formats](#visualization-formats): List, Tree, Graph, or Layered based on complexity and relationship patterns. See [Format Selection Guide](#format-selection-guide).
+
+**Step 5: Create the visualization**
+
+Build the Visualization section in the Quick Template using your chosen format. Start with high-level structure, then add details. See [Visualization Formats](#visualization-formats) for examples.
+
+**Step 6: Add legend and insights**
+
+Complete the Legend and Insights sections in the Quick Template if needed, documenting discoveries from mapping. See [Quality Checklist](#quality-checklist) before finalizing.
+
+---
+
+## Quick Template
+
+Copy this structure to `mapping-visualization-scaffolds.md`:
+
+```markdown
+# [Map Title]
+
+## Map Metadata
+
+**Purpose:** [Why this map exists, what decisions it informs]
+**Audience:** [Who will use this map]
+**Scope:** [What's included/excluded]
+**Date:** [YYYY-MM-DD]
+**Author:** [Name or team]
+
+## Nodes
+
+List all key elements:
+
+| Node ID | Name | Type | Description |
+|---------|------|------|-------------|
+| N1 | [Node name] | [Component/Concept/Person/Step] | [Brief description] |
+| N2 | [Node name] | [Type] | [Brief description] |
+| N3 | [Node name] | [Type] | [Brief description] |
+
+## Relationships
+
+Define connections between nodes:
+
+| From | To | Relationship Type | Description |
+|------|-----|-------------------|-------------|
+| N1 | N2 | [depends-on/calls/contains/leads-to] | [Details about this connection] |
+| N2 | N3 | [Type] | [Details] |
+
+## Groupings/Layers
+
+Organize nodes into logical groups:
+
+- **[Group 1 Name]:** N1, N2
+- **[Group 2 Name]:** N3, N4
+- **[Group 3 Name]:** N5, N6
+
+## Visualization
+
+[Insert your map using chosen format - see options below]
+
+## Legend
+
+**Node Types:**
+- [Symbol/Color] = [Type]
+
+**Relationship Types:**
+- → = [Meaning]
+- ⇒ = [Meaning]
+- ↔ = [Meaning]
+
+## Insights and Observations
+
+**Key Findings:**
+- [Important discovery from mapping]
+- [Unexpected dependency or pattern]
+- [Critical path or bottleneck]
+
+**Recommendations:**
+- [Action based on map insights]
+
+**Limitations:**
+- [What's not captured in this map]
+- [Known gaps or uncertainties]
+```
+
+---
+
+## Visualization Formats
+
+### Format 1: Simple List (< 10 nodes, simple relationships)
+
+```
+API Gateway
+├─→ Auth Service
+│   └─→ User Database
+├─→ Product Service
+│   ├─→ Product Database
+│   └─→ Cache Layer
+└─→ Payment Service
+    └─→ Payment Database
+```
+
+**When to use:** Linear flows, simple hierarchies, few cross-dependencies
+
+### Format 2: Tree Diagram (hierarchical relationships)
+
+```
+                    Application
+                        |
+        ┌──────────────┼──────────────┐
+        |              |              |
+    Frontend       Backend         Data
+        |              |              |
+    ┌───┴───┐      ┌───┴───┐      ┌───┴───┐
+   UI  Auth     API  Logic    DB  Cache
+```
+
+**When to use:** Org charts, taxonomies, clear parent-child relationships
+
+### Format 3: Network Graph (complex interconnections)
+
+```
+    ┌─────────┐
+    │  User   │
+    └────┬────┘
+         │
+    ┌────▼────┐     ┌──────────┐
+    │  Auth   │────→│  Logs    │
+    └────┬────┘     └──────────┘
+         │
+    ┌────▼────┐     ┌──────────┐
+    │ Service │────→│ Database │
+    └────┬────┘     └──────────┘
+         │              ▲
+         │              │
+    ┌────▼────┐         │
+    │  Cache  │─────────┘
+    └─────────┘
+```
+
+**When to use:** Microservices, complex dependencies, bi-directional relationships
+
+### Format 4: Layered Diagram (system architecture)
+
+```
+┌─────────────────────────────────────────────┐
+│  Presentation Layer                         │
+│  [Web UI]  [Mobile App]  [API Docs]        │
+└─────────────────────────────────────────────┘
+                    ↓
+┌─────────────────────────────────────────────┐
+│  Business Logic Layer                       │
+│  [Auth] [Users] [Products] [Payments]      │
+└─────────────────────────────────────────────┘
+                    ↓
+┌─────────────────────────────────────────────┐
+│  Data Layer                                 │
+│  [PostgreSQL]  [Redis]  [S3]               │
+└─────────────────────────────────────────────┘
+```
+
+**When to use:** System architectures, layered designs, clear abstraction levels
+
+### Format 5: Swimlane/Matrix (responsibilities, workflows)
+
+```
+| Step | Frontend | Backend | Database | External |
+|------|----------|---------|----------|----------|
+| 1. Request | Send login | - | - | - |
+| 2. Validate | - | Check credentials | Query users | - |
+| 3. Token | - | Generate JWT | - | - |
+| 4. Store | Receive token | - | Update session | Log event |
+| 5. Redirect | Show dashboard | - | - | - |
+```
+
+**When to use:** Process flows with multiple actors, workflow documentation
+
+---
+
+## Format Selection Guide
+
+**Choose based on:**
+
+| Characteristic | Recommended Format |
+|----------------|-------------------|
+| < 10 nodes, linear flow | Simple List |
+| Clear hierarchy, one parent per child | Tree Diagram |
+| Many cross-dependencies, cycles | Network Graph |
+| Multiple abstraction layers | Layered Diagram |
+| Multiple actors/systems in process | Swimlane/Matrix |
+| Time-based sequence | Swimlane or Simple List |
+| Spatial/geographic relationships | Custom diagram with coordinates |
+
+**Complexity thresholds:**
+- **10-20 nodes:** Use grouping and colors
+- **20-50 nodes:** Create multiple focused maps or use layered approach
+- **50+ nodes:** Definitely split into multiple maps
+
+---
+
+## Section Guidance
+
+### 1. Map Metadata
+
+**Purpose:** Be specific about the map's goal
+- ✓ "Understand microservices dependencies to identify deployment risks"
+- ✗ "Show system architecture"
+
+**Audience:** Tailor detail level to reader
+- Technical team: Include implementation details
+- Executives: Focus on high-level components and costs
+- New team members: Add more context and explanations
+
+**Scope:** Explicitly state boundaries
+- "Includes all production services; excludes development tools"
+- "Shows user-facing journey; excludes backend processing"
+- "Maps current state as of 2024-Q4; does not include planned features"
+
+### 2. Nodes
+
+**What to include:**
+- **ID**: Short identifier (N1, N2, or descriptive like "AUTH")
+- **Name**: Clear, consistent naming (same conventions throughout)
+- **Type**: Component, Concept, Person, Step, System, etc.
+- **Description**: Brief (< 20 words) explanation of purpose or role
+
+**Naming conventions:**
+- Use consistent casing (PascalCase, snake_case, or kebab-case)
+- Be specific: "User Authentication Service" not just "Auth"
+- Avoid acronyms unless universally understood
+
+**Examples:**
+```
+N1 | API Gateway | Service | Routes external requests to internal services
+N2 | Auth Service | Service | Validates user credentials and generates JWTs
+N3 | User DB | Data Store | PostgreSQL database storing user profiles
+```
+
+### 3. Relationships
+
+**Common relationship types:**
+
+**Dependency relationships:**
+- `depends-on` - A needs B to function
+- `requires` - A cannot start without B
+- `blocks` - A prevents B from proceeding
+- `enables` - A makes B possible
+
+**Data relationships:**
+- `reads-from` - A consumes data from B
+- `writes-to` - A modifies data in B
+- `sends-to` - A transmits messages/events to B
+- `receives-from` - A gets messages/events from B
+
+**Structural relationships:**
+- `contains` / `part-of` - Hierarchical containment
+- `is-a` / `extends` - Type relationships
+- `implements` - Interface implementation
+- `uses` / `calls` - Service invocation
+
+**Process relationships:**
+- `leads-to` / `follows` - Sequential steps
+- `triggers` - Event causation
+- `approves` / `rejects` - Decision flows
+- `escalates-to` - Authority chain
+
+**Specify directionality:**
+- Use clear arrows: A → B (A to B)
+- Note bi-directional: A ↔ B
+- Include cardinality if relevant: A →[1:N]→ B
+
+### 4. Groupings/Layers
+
+**When to group:**
+- Logical subsystems (Frontend, Backend, Data)
+- Organizational boundaries (Team A, Team B)
+- Phases or stages (Planning, Execution, Review)
+- Environments (Dev, Staging, Production)
+- Abstraction levels (Strategic, Tactical, Operational)
+
+**Grouping strategies:**
+- **By function**: All authentication-related nodes
+- **By owner**: All nodes maintained by Team X
+- **By layer**: All presentation-layer nodes
+- **By lifecycle**: All legacy vs. new nodes
+- **By criticality**: Core vs. optional nodes
+
+## Quality Checklist
+
+Before finalizing your map, verify:
+
+**Completeness:**
+- [ ] All critical nodes identified
+- [ ] All significant relationships documented
+- [ ] Groupings clearly labeled
+- [ ] Legend provided if > 3 relationship types
+
+**Clarity:**
+- [ ] Consistent naming conventions
+- [ ] Clear directionality on relationships
+- [ ] Appropriate level of detail for audience
+- [ ] No overlapping or ambiguous connections
+
+**Accuracy:**
+- [ ] Relationships verified with SMEs or documentation
+- [ ] Current state (not outdated)
+- [ ] No missing critical dependencies
+- [ ] Scope boundaries clearly stated
+
+**Usability:**
+- [ ] Can target audience understand without explanation?
+- [ ] Is the visualization scannable (not a "hairball")?
+- [ ] Are insights or key findings highlighted?
+- [ ] Is next action or decision clear?
+
+**Technical:**
+- [ ] File saved as `mapping-visualization-scaffolds.md`
+- [ ] Markdown formatting correct
+- [ ] Links and references work
+- [ ] Version/date included
+
+---
+
+## Common Patterns by Domain
+
+**Software Architecture:**
+- Nodes: Services, databases, message queues, APIs
+- Relationships: Calls, reads/writes, publishes/subscribes
+- Groupings: Layers (presentation, business, data)
+
+**Knowledge/Concept Mapping:**
+- Nodes: Concepts, theories, terms, examples
+- Relationships: Is-a, has-a, leads-to, contradicts
+- Groupings: Themes, disciplines, abstraction levels
+
+**Project Planning:**
+- Nodes: Tasks, milestones, deliverables
+- Relationships: Depends-on, blocks, follows
+- Groupings: Phases, sprints, teams
+
+**Organizational:**
+- Nodes: People, teams, roles, functions
+- Relationships: Reports-to, collaborates-with, approves
+- Groupings: Departments, locations, levels
+
+**Process/Workflow:**
+- Nodes: Steps, decisions, handoffs
+- Relationships: Leads-to, triggers, approves/rejects
+- Groupings: Swimlanes (actors), phases
+
+---
+
+## Tips for Effective Maps
+
+**Start Simple:**
+1. Begin with 5-10 most important nodes
+2. Add critical relationships only
+3. Expand if needed, but resist over-complication
+
+**Use Visual Hierarchy:**
+- Size: Larger nodes = more important
+- Position: Top = start, Bottom = end (for flows)
+- Grouping: Visual proximity = logical grouping
+
+**Iterate:**
+- Create draft, get feedback, refine
+- Test understanding with someone unfamiliar
+- Simplify based on confusion points
+
+**Know When to Split:**
+- If map has > 30 nodes, consider multiple maps
+- Create one high-level overview + detailed sub-maps
+- Link related maps together
+
+**Common Improvements:**
+- Add color coding for node types
+- Use different line styles for relationship types
+- Include metrics or attributes on nodes (e.g., latency, importance)
+- Highlight critical paths or bottlenecks