map-workflows-guide

MAP Workflows Guide

This skill helps you choose the optimal MAP workflow for your development tasks. MAP Framework provides 5 specialized workflows, each optimized for different scenarios with varying token costs, learning capabilities, and quality gates.

Quick Decision Tree

Answer these 5 questions to find your workflow:

1. Is this throwaway code or a quick experiment?
   YES  → Use /map-fast (40-50% tokens, no learning)
   NO   → Continue to question 2

2. Are you debugging/fixing a specific bug or test failure?
   YES  → Use /map-debug (70-80% tokens, focused analysis)
   NO   → Continue to question 3

3. Are you refactoring existing code or restructuring modules?
   YES  → Use /map-refactor (70-80% tokens, dependency analysis)
   NO   → Continue to question 4

4. Is this critical infrastructure or security-sensitive code?
   YES  → Use /map-feature (100% tokens, maximum validation)
   NO   → Continue to question 5

5. Is this a production feature you'll maintain long-term?
   YES  → Use /map-efficient (60-70% tokens, batched learning) ← RECOMMENDED
   NO   → Re-evaluate based on specific constraints

---

Workflow Comparison Matrix

Aspect	/map-fast	/map-efficient	/map-feature	/map-debug	/map-refactor
Token Cost	40-50%	60-70%	100% (baseline)	70-80%	70-80%
Learning	❌ None	✅ Batched	✅ Per-subtask	✅ Per-subtask	✅ Per-subtask
Quality Gates	Basic	Essential	All 8 agents	Focused	Focused
Impact Analysis	❌ Skipped	⚠️ Conditional	✅ Always	✅ Yes	✅ Yes
Best For	Throwaway	Production	Critical	Bugs	Refactoring
Recommendation	Never use	DEFAULT	High-risk	Issues	Changes

---

Detailed Workflow Descriptions

1. /map-fast — Quick Prototypes ⚡

Use this when:

• Creating throwaway code you'll discard after testing
• Running experiments to validate ideas
• Spike solutions to explore feasibility
• Non-critical helper scripts or utilities

What you get:

• ✅ Full implementation (Actor generates code)
• ✅ Basic validation (Monitor checks correctness)
• ✅ Quality check (Evaluator scores solution)
• ❌ NO impact analysis (Predictor skipped entirely)
• ❌ NO learning (Reflector/Curator skipped)

Trade-offs:

• Saves 50-60% tokens vs /map-feature
• Playbook never improves (no patterns stored)
• Cipher knowledge never accumulates
• Minimal quality gates (only basic checks)
• Cannot reuse learned patterns in future tasks

Example tasks:

• "Quick prototype for authentication approach"
• "Spike solution to test performance impact"
• "Throwaway script to explore API design"

Command syntax:

/map-fast [task description]

When to AVOID:

• ❌ Never for production code
• ❌ Never for code you'll refactor later
• ❌ Never for security-critical logic
• ❌ Never to save tokens on important work

See also: resources/map-fast-deep-dive.md

---

2. /map-efficient — Production Features (RECOMMENDED) 🎯

Use this when:

• Building production features (moderate complexity)
• Most of your development work
• You want full learning but need token efficiency
• Standard feature implementation with familiar patterns

What you get:

• ✅ Full implementation (Actor)
• ✅ Comprehensive validation (Monitor with feedback loops)
• ✅ Quality gates (Evaluator approval)
• ✅ Impact analysis (Predictor runs conditionally)
• ✅ Batched learning (Reflector/Curator run once at end)

Optimization strategy:

• Conditional Predictor: Runs only if risk detected (security, breaking changes)
• Batched Learning: Reflector/Curator run ONCE after all subtasks complete
• Result: 35-40% token savings vs /map-feature while preserving learning
• Same quality gates: Monitor still validates each subtask

When Predictor runs:

• Modifies authentication/security code
• Introduces breaking changes
• High complexity detected
• Multiple files affected

Example tasks:

• "Implement user registration with email validation"
• "Add pagination to blog posts API"
• "Create dashboard analytics component"
• "Build shopping cart feature"

Command syntax:

/map-efficient [task description]

Quality guarantee: Despite token optimization, preserves:

• Per-subtask validation (Monitor always checks)
• Complete implementation feedback loops
• Full learning (batched, not skipped)
• Playbook growth from all tasks

See also: resources/map-efficient-deep-dive.md

---

3. /map-feature — Critical Features 🏗️

Use this when:

• Implementing security-critical functionality
• First-time complex features requiring maximum validation
• High-risk changes affecting many systems
• You need complete assurance before production
• Learning is critical for future similar tasks

What you get:

• ✅ Full implementation (Actor)
• ✅ Comprehensive validation (Monitor with loops)
• ✅ Per-subtask impact analysis (Predictor always runs)
• ✅ Quality gates (Evaluator always runs)
• ✅ Per-subtask learning (Reflector/Curator after each subtask)

Trade-offs:

• 100% token cost (no optimization applied)
• Slower execution (maximum agent cycles)
• Maximum quality assurance
• Most comprehensive learning (frequent reflections)
• Best for high-stakes implementations

When this is required:

• Authentication/authorization systems
• Payment processing
• Database schema changes
• Multi-service coordination
• Code that affects many dependencies

Example tasks:

• "Implement secure JWT authentication system"
• "Refactor database schema for multi-tenancy"
• "Add payment processing via Stripe"
• "Build real-time notification system"

Command syntax:

/map-feature [task description]

Agent pipeline:

TaskDecomposer → Actor → Monitor → Predictor →
Evaluator → Reflector → Curator → [Next subtask]

See also: resources/map-feature-deep-dive.md

---

4. /map-debug — Bug Fixes 🐛

Use this when:

• Fixing specific bugs or defects
• Resolving test failures
• Investigating runtime errors
• Performing root cause analysis
• Diagnosing unexpected behavior

What you get:

• ✅ Focused implementation (Actor targets root cause)
• ✅ Validation (Monitor verifies fix)
• ✅ Root cause analysis
• ✅ Impact assessment (Predictor)
• ✅ Learning (Reflector/Curator)

Specialized features:

• Error log analysis
• Stack trace interpretation
• Test failure diagnosis
• Regression prevention

Example tasks:

• "Fix failing tests in auth.test.ts"
• "Debug TypeError in user service"
• "Resolve race condition in async code"
• "Fix memory leak in notification handler"

Command syntax:

/map-debug [issue description or error message]

Include in request:

• Error message/stack trace
• When it occurs (specific scenario)
• What the expected behavior is
• Relevant log files if available

See also: resources/map-debug-deep-dive.md

---

5. /map-refactor — Code Restructuring 🔧

Use this when:

• Refactoring existing code for readability
• Improving code structure or design
• Cleaning up technical debt
• Renaming/reorganizing modules
• Extracting common logic

What you get:

• ✅ Implementation (Actor)
• ✅ Validation (Monitor)
• ✅ Dependency impact analysis (Predictor focused on dependencies)
• ✅ Quality gates (Evaluator)
• ✅ Learning (Reflector/Curator)

Specialized for:

• Breaking change detection
• Dependency tracking
• Migration planning
• Careful phased refactoring

Example tasks:

• "Refactor auth service to separate concerns"
• "Extract common validation logic into shared module"
• "Rename User model to Account throughout codebase"
• "Convert callback-based API to promise-based"

Command syntax:

/map-refactor [refactoring description]

Impact analysis includes:

• Which files/modules depend on changed code
• Potential breaking changes
• Migration strategy
• Scope of refactoring

See also: resources/map-refactor-deep-dive.md

---

Understanding MAP Agents

MAP workflows orchestrate 8 specialized agents, each with specific responsibilities:

Execution & Validation Agents

TaskDecomposer — Breaks goal into subtasks

• Analyzes requirements
• Creates atomic, implementable subtasks
• Defines acceptance criteria for each
• Estimates complexity

Actor — Writes code and implements

• Generates implementation
• Makes file changes
• Uses playbook patterns
• Queries cipher for relevant knowledge

Monitor — Validates correctness

• Checks implementation against criteria
• Runs tests to verify
• Identifies issues
• Feedback loop: Returns to Actor if invalid

Evaluator — Quality gates

• Scores implementation quality (0-10)
• Checks completeness
• Approves/rejects solution
• Feedback loop: Returns to Actor if score < threshold

Analysis Agents

Predictor — Impact analysis

• Analyzes dependencies
• Predicts side effects
• Identifies risks and breaking changes
• Conditional in /map-efficient (runs if risk detected)
• Always in /map-feature (runs per subtask)

Learning Agents

Reflector — Pattern extraction

• Analyzes what worked and failed
• Extracts reusable patterns
• Searches cipher for existing knowledge
• Prevents duplicate pattern storage
• Batched in /map-efficient (runs once at end)
• Per-subtask in /map-feature (extracts frequently)

Curator — Knowledge management

• Updates playbook with new patterns
• Deduplicates against cipher
• Syncs high-quality patterns (helpful_count ≥ 5)
• Maintains pattern metadata
• Batched in /map-efficient (runs once at end)

Optional Agent

Documentation-Reviewer — Documentation validation

• Reviews completeness
• Checks consi

---

Content truncated.