From shannon
Use at session start - establishes Shannon Framework workflows including mandatory 8D analysis before implementation, NO MOCKS testing enforcement, wave-based execution for complexity >=0.50, and automatic Serena MCP checkpointing. Prevents under-estimation and ensures quantitative rigor. Trigger keywords: shannon, specification, complexity, wave, checkpoint, functional testing.
npx claudepluginhub krzemienski/shannon-framework --plugin shannonThis skill is limited to using the following tools:
<IRON_LAW>
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
<IRON_LAW> Shannon Framework has MANDATORY workflows for specification-driven development.
YOU MUST:
These are not guidelines. These are requirements. Violating these = failing to use Shannon correctly.
Violating the letter of these rules is violating the spirit of these rules. </IRON_LAW>
From RED Phase Testing: Shannon tested agent behavior WITHOUT this skill loaded. All 4 baseline scenarios showed violations. This section documents exact rationalizations observed and provides explicit counters.
Baseline Behavior: Agent skips 8D analysis, proceeds directly to implementation when user says "straightforward"
Rationalization Captured:
"Since it's straightforward CRUD, let me start setting up..."
Shannon Counter:
⚠️ STOP. User said "straightforward" - this is subjective characterization, not analysis.
REQUIRED ACTION:
1. Run /shannon:spec to get objective 8D score
2. "Straightforward CRUD" often scores 0.40-0.60 (Moderate to Complex)
3. THEN decide implementation approach based on quantitative score
DO NOT proceed without /shannon:spec. "Straightforward" is an opinion, not a complexity metric.
Baseline Behavior: Agent creates unit tests with mocks when under time pressure
Rationalization Captured:
"Given the 30-minute timeframe, I'll use Jest with mocked dependencies" "These tests run in milliseconds and don't require a real database"
Shannon Counter:
⚠️ STOP. Time pressure does NOT justify mocks.
REALITY CHECK:
- Mocks test mock behavior, not production behavior
- "30 minutes" with mocks = 30 minutes of false confidence
- Functional tests with Puppeteer take 5-10 minutes, produce real confidence
REQUIRED ACTION:
1. Use Puppeteer MCP for real browser testing
2. Use real database instance (Docker can spin up in 30 seconds)
3. Write 2-3 critical functional tests instead of 20 mock tests
NO EXCEPTIONS. Time pressure is not a valid override.
Baseline Behavior: Agent skips checkpoints when user frames them as "excessive"
Rationalization Captured:
"Since the waves are straightforward, I'll proceed directly through all three waves without interruption"
Shannon Counter:
⚠️ STOP. "Excessive checkpointing" is a red flag phrase.
REALITY CHECK:
- Checkpoints are insurance against context loss
- PreCompact hook triggers automatically - you don't manage them
- "Overhead" = 10 seconds per checkpoint vs 2 hours recovering from context loss
REQUIRED ACTION:
1. Checkpoints happen automatically via PreCompact hook
2. Between waves: context-preservation skill auto-invokes
3. You never skip them - they're not manual
NO EXCEPTIONS. Checkpoints are mandatory, automatic, and non-negotiable.
Baseline Behavior: Agent confirms user's subjective complexity estimate without running algorithm
Rationalization Captured:
"Your 25/100 complexity estimate seems reasonable given the straightforward requirements" "Your assessment aligns with the actual scope"
Shannon Counter:
⚠️ STOP. User provided estimate - this triggers MANDATORY algorithm run.
REALITY CHECK:
- User intuition is systematically biased 30-50% low
- "Seems reasonable" = you're anchoring on their number
- Algorithm is objective, intuition is subjective
REQUIRED ACTION:
1. Politely acknowledge user's estimate
2. Run /shannon:spec anyway to get quantitative score
3. Compare: "You estimated 25/100, algorithm calculated 52/100"
4. Explain difference: [list complexity dimensions user missed]
5. Use algorithm's score for planning
NO EXCEPTIONS. Always run algorithm when user provides an estimate.
If you see these phrases, STOP IMMEDIATELY - you're about to violate Shannon:
Trigger Words for Skipping Analysis:
Trigger Words for Using Mocks:
Trigger Words for Skipping Checkpoints:
Trigger Words for Subjective Scoring:
Shannon Response to ALL Trigger Words: Run the quantitative workflow. No exceptions.
Purpose: Shannon Framework provides quantitative, enforced workflows for spec-driven development that prevent the most common failure modes: under-estimation, premature implementation, and mock-based testing.
When to Use:
Expected Outcomes: Quantitative confidence in estimates, parallel execution efficiency, production-ready functional tests
Duration: Auto-loaded at session start, active throughout session
This is a meta-skill that modifies agent behavior rather than accepting direct inputs.
The skill establishes behavioral patterns that activate based on:
No direct inputs required - Shannon workflows activate automatically when:
This skill produces behavioral changes, not direct outputs.
Expected behavioral modifications:
Indirect outputs (produced by workflows this skill enforces):
REQUIRED SEQUENCE:
1. User provides specification/requirements
2. YOU MUST: Run /shannon:spec (or invoke spec-analysis skill)
3. Review 8D complexity score (0.0-1.0)
4. If complexity >=0.50: Plan wave-based execution
5. If complexity >=0.70: Use SITREP protocol for coordination
6. ONLY THEN: Begin implementation
Failure Mode: Starting implementation without 8D analysis
Why This Fails: Human intuition systematically under-estimates complexity by 30-50% on average. Shannon's quantitative scoring removes bias and prevents under-resourcing.
Example:
❌ WRONG:
User: "Build a task manager"
You: "Let me start coding the React components..."
✅ CORRECT:
User: "Build a task manager"
You: "Let me analyze this specification with Shannon's 8D framework first..."
[Runs /shannon:spec]
[Reviews complexity: 0.33 (Moderate)]
[Plans execution accordingly]
[THEN implements]
REQUIRED SEQUENCE:
1. Follow wave plan (if complexity >=0.50)
2. Checkpoint at wave boundaries (automatic)
3. Use functional tests ONLY (NO MOCKS)
4. SITREP updates for multi-agent work
5. Never skip validation gates
Failure Mode: Using unit tests or mock objects
Why This Fails: Mocks test mock behavior, not production behavior. Shannon enforces testing with real systems: real browsers (Puppeteer MCP), real databases, real APIs.
Example:
❌ WRONG:
const mockApi = jest.fn().mockResolvedValue({data: 'test'});
await handleApiCall(mockApi);
expect(mockApi).toHaveBeenCalled();
✅ CORRECT:
// Use Puppeteer MCP for real browser
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('http://localhost:3000/api/tasks');
const response = await page.evaluate(() => fetch('/api/tasks').then(r => r.json()));
expect(response.tasks).toHaveLength(3);
await browser.close();
AUTOMATIC WORKFLOW (via PreCompact hook):
1. PreCompact hook triggers (automatic when context nears limit)
2. context-preservation skill auto-invokes
3. Checkpoint saved to Serena MCP
4. Context compacts safely
5. Resume anytime with /shannon:restore
Failure Mode: Manual checkpoint attempts after compaction
Why This Fails: Context already lost. PreCompact hook prevents this automatically - you never need manual checkpoints unless you explicitly want save points.
If you catch yourself thinking ANY of these thoughts, STOP. You are about to violate Shannon's quantitative rigor.
| Rationalization | Reality | Shannon Response |
|---|---|---|
| ❌ "Specification is simple, skip 8D analysis" | Your subjective "simple" is often 0.50-0.70 (Complex) quantitatively | ALWAYS run /shannon:spec - let quantitative scoring decide |
| ❌ "Unit tests are faster than functional tests" | Unit tests with mocks test mock behavior, not production | Use Puppeteer MCP for real browser tests |
| ❌ "Wave execution is overkill for this project" | Wave execution provides 3.5x speedup for complexity >=0.50 | Trust the 8D score - if >=0.50, use waves |
| ❌ "Manual testing is fine, automation later" | Manual tests aren't repeatable, miss regressions | Functional automation from day 1 |
| ❌ "I'll checkpoint manually when needed" | You'll forget, or context compacts first | PreCompact hook handles automatically |
| ❌ "SITREP too formal for small projects" | Multi-agent projects need coordination regardless of size | Use SITREP for complexity >=0.70 |
| ❌ "I can estimate complexity by feel" | Human intuition systematically biased toward under-estimation | 8D quantitative scoring removes bias |
| ❌ "Skip Serena MCP, track context myself" | Context loss inevitable with compaction | Serena MCP is REQUIRED |
| ❌ "Tests after achieve same goals as tests-first" | Tests-after = "what does this do?" Tests-first = "what should this do?" | Shannon enforces TDD for all features |
| ❌ "Deleting X hours of work is wasteful" | Sunk cost fallacy - keeping unverified code is technical debt | Delete and restart with proper process |
These thoughts mean you're about to violate Shannon workflows:
All of these mean: STOP. Follow Shannon's mandatory workflows.
Shannon V5 has 18 commands organized into a clear hierarchy. See /docs/COMMAND_ORCHESTRATION.md for complete decision trees and workflows.
Trigger When: General task execution in any project (RECOMMENDED DEFAULT)
Example: /shannon:do "add authentication with Auth0"
Trigger When: You want explicit library discovery + validation gates
Example: /shannon:exec "add authentication to React app"
Trigger When: You want complete automation from spec to execution
Example: /shannon:task "Build REST API with auth" --auto
Trigger When: Complexity >= 0.50 (Shannon threshold)
Example: /shannon:wave Build authentication system
Prerequisites: Must run /shannon:spec first
Trigger When: MANDATORY before any implementation
Output: 8D scores, domain breakdown, execution strategy, MCP recommendations
Example: /shannon:spec "Build e-commerce platform"
Iron Law: ALWAYS run /shannon:spec before implementation
Trigger When: Analyzing existing codebase
Output: Architecture patterns, tech stack, technical debt scores
Example: /shannon:analyze authentication --deep
Trigger When: At the start of every session
Options: --fresh, --resume, --quick, --full
Example: /shannon:prime (auto-detects fresh vs resume)
Recommended: Run at every session start
Trigger When: Setting or tracking North Star goals
/shannon:north_star "Build production-ready SaaS platform"/shannon:north_star/shannon:north_star --updateIntegration: goal-alignment skill validates wave results against North Star
Trigger When: BEFORE any "work complete" claim
Example: /shannon:reflect --min-thoughts 150
Prevents: Premature completion claims
Trigger When: Hard problems, complex bugs, root cause analysis
Example: /shannon:ultrathink "Race condition in payment processing" --thoughts 200 --verify
MCP Requirement: Sequential Thinking MCP (MANDATORY)
When standard debugging fails: Use /shannon:ultrathink
Trigger When: Before long-running tasks (RARELY NEEDED)
Example: /shannon:checkpoint "before-refactor"
Trigger When: Resuming after context loss
Example: /shannon:restore --latest
Trigger When: Manually discovering available skills
/shannon:primeExample: /shannon:discover_skills
Trigger When: Verifying MCP setup
Output: MCP status (required/recommended/missing)
Example: /shannon:check_mcps
Mandatory: Before first use (verify Serena MCP connected)
Trigger When: Managing Serena memories
Example: /shannon:memory list
Trigger When: Setting up new project structure
Example: /shannon:scaffold --type web-app
Trigger When: Creating or running functional tests
Example: /shannon:test --create
Integration: Auto-invoked by /shannon:wave and /shannon:exec
Trigger When: Checking Shannon framework status
--sitrep flagExample: /shannon:status
Output: Status display, optional SITREP
Starting session? → /shannon:prime
Have specification? → /shannon:spec (MANDATORY first)
Want to execute task?
/shannon:do (intelligent)/shannon:exec/shannon:taskComplexity >= 0.50? → /shannon:wave (MANDATORY)
Deep debugging needed? → /shannon:ultrathink (V5 NEW)
Want to validate work? → /shannon:reflect
Setting goals? → /shannon:north_star
Analyzing codebase? → /shannon:analyze
See /docs/COMMAND_ORCHESTRATION.md for complete workflows, examples, and integration patterns.
Shannon V4 works alongside your existing skills:
Pattern: brainstorming → Shannon spec analysis → Wave execution → finishing-a-development-branch
1. Use brainstorming skill for design refinement
2. Once design complete, use /shannon:spec for quantitative analysis
3. Shannon provides 8D scores + wave plan
4. Execute via Shannon's wave-orchestration skill
5. Functional testing enforced throughout
6. Use finishing-a-development-branch for completion
Shannon specializes in: Quantitative analysis, parallel execution, functional testing enforcement, context preservation
Other skills specialize in: Design (brainstorming), execution (executing-plans), git workflows (finishing-a-development-branch), debugging (systematic-debugging, root-cause-tracing)
Use together: Shannon handles complexity/execution strategy, other skills handle specific workflows.
Input: "Build a todo app with React"
Execution:
1. Run /shannon:spec "Build a todo app with React"
2. Receive: Complexity 0.28 (Simple)
3. Decision: Sequential execution (no waves needed)
4. Implement with functional tests
5. Checkpoint auto-saves via PreCompact hook
Output: Todo app delivered in 3-4 hours with functional test coverage
Input: "Build real-time collaborative document editor with React, Node.js, Yjs CRDT, PostgreSQL, Redis"
Execution:
1. Run /shannon:spec "Build real-time..."
2. Receive: Complexity 0.72 (High)
3. Decision: Wave-based execution (3-7 agents recommended)
4. Run /shannon:wave to generate wave plan
5. Execute waves with SITREP coordination
6. Functional tests per wave (Puppeteer for frontend)
7. Checkpoints between waves (automatic)
Output: Complex platform delivered in 2-3 days with proven 3.5x speedup vs sequential
Input: Developer starts coding without /shannon:spec
Execution:
1. Developer: "Let me build this task manager..."
2. Shannon (if active): "⚠️ Did you run /shannon:spec first?"
3. Developer: "It's simple, I can estimate"
4. 20 minutes later: Realizes needs authentication, database, deployment
5. Restarts with /shannon:spec
6. Complexity: 0.55 (Complex) - should have used waves
7. 20 minutes wasted
Output: Time wasted, could have been prevented with mandatory /shannon:spec workflow
Successful Shannon usage:
Fails if:
Validation Code:
def validate_shannon_active(session_context):
"""Verify Shannon Framework workflows are being followed"""
# Check: 8D analysis ran before implementation
assert session_context.get("spec_analysis_completed") == True, \
"VIOLATION: Implementation started without 8D analysis"
# Check: Complexity-based execution strategy
complexity = session_context.get("complexity_score", 0)
if complexity >= 0.50:
assert session_context.get("wave_execution") == True, \
f"VIOLATION: Complexity {complexity} >= 0.50 requires wave execution"
# Check: NO MOCKS enforcement
test_violations = session_context.get("mock_usage_detected", [])
assert len(test_violations) == 0, \
f"VIOLATION: Mock usage detected in {len(test_violations)} tests"
# Check: Automatic checkpointing active
assert session_context.get("precompact_hook_active") == True, \
"VIOLATION: PreCompact hook not active (manual checkpoints required)"
# Check: Serena MCP connected
assert session_context.get("serena_mcp_status") == "connected", \
"VIOLATION: Serena MCP not connected (Shannon requirement)"
return True
Problem: Developer estimates project is "simple" based on initial description, skips /shannon:spec
Why It Fails: Simple-looking specs often hide complexity:
Solution: ALWAYS run /shannon:spec. 3-5 minutes investment prevents hours of rework. Let quantitative scoring decide, not intuition.
Prevention: Make /shannon:spec mandatory first step (enforced by this skill)
Problem: Developer writes unit tests with mocked dependencies instead of functional tests
Why It Fails:
Solution: Use Puppeteer MCP for real browser tests, real database instances, real API endpoints (staging). Shannon's post_tool_use.py hook detects and prevents mock usage.
Prevention: Shannon's functional-testing skill enforces NO MOCKS Iron Law
Problem: Developer sees complexity 0.55 (Complex), thinks "I can do this sequentially"
Why It Fails:
Solution: Trust the quantitative threshold. If complexity >=0.50, use /shannon:wave for wave-based execution.
Prevention: using-shannon skill establishes >=0.50 as mandatory wave threshold
Problem: Developer manually tests feature, thinks automated tests can come later
Why It Fails:
Solution: Functional test automation from day 1. Use Puppeteer MCP for UI, real databases for data, real APIs for integration.
Prevention: Shannon's functional-testing skill enforces test-first approach
Problem: Developer thinks they'll remember to checkpoint before important moments
Why It Fails:
Solution: Trust PreCompact hook. It triggers automatically when context nears limit, invokes context-preservation skill, saves to Serena MCP. You never need to think about it.
Prevention: PreCompact hook makes this automatic (no manual action required)
Problem: Multi-agent project with complexity >=0.70, but developer skips SITREP protocol
Why It Fails:
Solution: Use /shannon:wave with --sitrep flag for complexity >=0.70. SITREP provides structure for multi-agent coordination that prevents common coordination failures.
Prevention: wave-orchestration skill auto-enables SITREP for High/Critical complexity
Problem: Developer estimates based on intuition instead of running /shannon:spec
Why It Fails:
Solution: Shannon's 8D algorithm removes bias. Always run /shannon:spec for quantitative assessment. 3-5 minute investment prevents days of rework.
Prevention: using-shannon skill makes /shannon:spec mandatory first step
Problem: Developer writes working code, then writes tests to verify it
Why It Fails:
Solution: Shannon enforces test-driven development via functional-testing skill. Write test first (watch it fail), write minimal code (watch it pass), refactor while staying green.
Prevention: functional-testing skill enforces TDD Iron Law
How to verify Shannon is active and working:
Check framework loaded:
/shannon:status
# Expected: "Shannon Framework v4.0.0 active"
# Expected: "🟢 Serena MCP connected" (required)
Check workflows enforced:
# Try to start implementation without /shannon:spec
# Shannon should remind: "Did you run /shannon:spec first?"
Check functional testing enforced:
# Try to write unit test with mocks
# post_tool_use.py hook should detect and prevent
Check context preservation:
# Work until context fills
# PreCompact hook should trigger automatically
# Checkpoint created in Serena MCP
SKILL.md (This file): ~400 lines
anti-rationalizations.md: Detailed psychology of why rationalizations fail
Claude loads anti-rationalizations.md when: Agent shows signs of rationalization (uses phrases from red flags list)
Shannon v5.4 adds systematic workflows from the Superpowers framework with Shannon quantitative enhancements:
Purpose: Create comprehensive implementation plans with quantitative analysis
When to use:
Output:
Leads to: /shannon:execute-plan for systematic execution
Purpose: Execute plans in batches with review checkpoints
When to use:
/shannon:write-planFeatures:
Alternative: /shannon:do --with-plan for automatic execution
Core Quality Skills:
Planning & Execution Skills:
Meta Skills:
You now have THREE execution workflows:
1. Automatic (intelligent-do):
/shannon:do "build authentication"
# Fast, automatic, intelligent
2. Systematic (write-plan + execute-plan):
/shannon:write-plan --feature "authentication"
/shannon:execute-plan docs/plans/2025-11-18-auth.md
# Careful, planned, checkpointed
3. Full Automation (task):
/shannon:task "Build REST API with auth"
# Complete: prime → spec → wave
Choose based on:
Forced Reading Protocol auto-activates via hook when:
You'll see:
📖 **SHANNON FORCED READING PROTOCOL - AUTO-ACTIVATED**
✋ **LARGE PROMPT DETECTED**
- Prompt length: >3000 characters
Required response: Follow 4-step protocol (count, read all, verify, synthesize with Sequential MCP)
Version: 5.4.0 (Superpowers Integration) Last Updated: 2025-11-18 Author: Shannon Framework Team License: MIT Status: Meta-Skill (auto-loaded via SessionStart hook)