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