Add cybernetic system analysis skill #24
Conversation
Enables systematic analysis of complex systems using feedback loops, requisite variety, VSM, and leverage points from Wiener, Beer, Ashby, and Meadows. 🤖 Generated with Claude Code Co-Authored-By: Claude <[email protected]>
WalkthroughThree new documentation files are added to introduce cybernetic analysis frameworks: a comprehensive Cybernetic System Analysis skill guide with four-phase workflow, a Leverage Points reference documenting Donella Meadows' framework, and a Viable Systems Model (VSM) diagnostic guide with real-world examples. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes These are documentation-only additions with no executable logic or code. Review effort centers on verifying factual accuracy of frameworks, consistency of terminology, clarity of explanations, and appropriateness of software examples. Low complexity due to homogeneous content type and no interdependencies to validate. Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (6)
skills/systems-thinking/cybernetic-analysis/leverage-points.md (1)
11-36: Add language specification to fenced code blocks (MD040).Multiple code blocks throughout the file lack language specification. While these are examples rather than executable code, the linter expects explicit language tags for consistency and tooling compatibility.
Examples at lines 32–36, 75–78, 114–117, 169–172, 212–215, 254–257.
Apply a consistent language tag (e.g.,
```text,```yaml, or```plaintext) to all example blocks. This ensures predictable rendering and future Markdown tooling integration.Example fix:
- ``` + ```text Problem: Service timing out Parameter fix: Increase timeout to 10s (low leverage) Better: Add circuit breaker (leverage #8)Apply the same pattern to all other code blocks in the file.
skills/systems-thinking/cybernetic-analysis/vsm-guide.md (2)
229-345: Use proper Markdown headings (###) instead of bold emphasis for pattern names.Lines 229–335 use
**Pattern: Xxx**with code blocks, but these should be actual Markdown headings (### Pattern: Xxx). This ensures:
- Proper document outline and navigation
- Correct heading hierarchy for accessibility tools
- Consistent structure matching leverage-points.md
Current violations:
- Lines 229, 234, 244, 256, 267, 280, 290, 301, 312, 322, 334 (MD036)
Example fix (lines 229–243):
- **Pattern: Visibility First** + ### Pattern: Visibility First - Make system state observable before attempting control ...Apply the same pattern conversion to all pattern sections.
74-78: Add language specification to fenced code blocks (MD040).Like leverage-points.md, multiple example blocks lack language tags. Add
```textor```yamlto all code/example blocks for consistency and tooling compatibility.Also applies to: 113-117, 168-172, 211-215, 253-257, 301-306, 312-320, 322-330, 334-341
skills/systems-thinking/cybernetic-analysis/SKILL.md (3)
217-346: Use proper Markdown headings (###) instead of bold emphasis for pattern names.Lines 229, 234, 244, 256, 267, 280, 290, 301, 312, 322, 334 use
**Pattern: Xxx**but should use### Pattern: Xxxfor proper document structure and accessibility. This affects:
- Outline/TOC generation
- Accessibility for assistive tech
- Consistency with Markdown standards
Current violations: "Visibility First", "Negative Feedback (Balancing)", "Positive Feedback (Reinforcing)", "Variety Amplification", "Variety Attenuation", "Reduce Delay", "Reduce Distortion", "Complete Information Channels", "Define Set Points", "Automatic Regulation", "Goal Alignment".
Example fix (lines 229–242):
- #### Adding Feedback Loops - - **Pattern: Visibility First** - - Make system state observable before attempting control + #### Adding Feedback Loops + + ##### Pattern: Visibility First + - Make system state observable before attempting controlNote: Adjust heading level to
#####(h5) to nest under h4 sections.
225-346: Add language specification to fenced code blocks (MD040).Lines 125, 235, 245, 257, 268, 281, 291, 302, 313, 323, 335 have code/example blocks without language tags. Add
```textor similar for consistency across all three documentation files.Example (lines 235–242):
- ``` + ```text Problem: Service overload Cybernetic: Missing balancing feedback loop Intervention: - Detect: Monitor queue depth, latency, error rate - Decide: Threshold-based triggers - Act: Circuit breaker, rate limiter, load sheddingApply to all pattern sections.
1-448: Markdown formatting recommendations (MD036, MD040) for consistency and accessibility.Three issues affect document structure and tooling:
Emphasis-as-Heading (MD036) — vsm-guide.md (lines 229–335) and SKILL.md (lines 229–335) use bold
**Pattern: Xxx**instead of proper headings### Pattern: Xxx. This affects:
- Document outline/TOC generation
- Accessibility (assistive tech relies on heading hierarchy)
- Consistent structure across reference materials
Fenced Code Blocks Without Language (MD040) — All three files have example blocks without language specs:
- leverage-points.md: lines 32, 75, 114, 169, 212, 254
- vsm-guide.md: lines 75, 114, 169, 212, 254, 302, 313, 323, 335
- SKILL.md: lines 125, 235, 245, 257, 268, 281, 291, 302, 313, 323, 335
Add
```text,```yaml, or```plaintextto all blocks for predictable rendering and future tooling integration.Recommendation: Before merging, run
markdownlinton all three files to confirm these are the only issues and apply fixes uniformly.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
skills/systems-thinking/cybernetic-analysis/SKILL.md(1 hunks)skills/systems-thinking/cybernetic-analysis/leverage-points.md(1 hunks)skills/systems-thinking/cybernetic-analysis/vsm-guide.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
skills/systems-thinking/cybernetic-analysis/leverage-points.md
[style] ~73-~73: To elevate your writing, try using a synonym here.
Context: ...** Structure constrains behavior but is hard to change. Often requires rebuilding. ...
(HARD_TO)
[style] ~83-~83: Consider using a different adjective in this context to strengthen your wording.
Context: ... to use:** - Current structure prevents good solutions - System needs fundamental re...
(GOOD_ALTERNATIVE)
[style] ~349-~349: As an alternative to the over-used intensifier ‘extremely’, consider replacing this phrase.
Context: ...w people think about the system. Why extremely powerful: Paradigm shift changes everything - ...
(EN_WEAK_ADJECTIVE)
[style] ~466-~466: Consider using a different verb for a more formal wording.
Context: ...ghting Symptoms Symptom: Constantly fixing tactical problems Why bad: Not addr...
(FIX_RESOLVE)
skills/systems-thinking/cybernetic-analysis/SKILL.md
[style] ~411-~411: Consider using a different verb for a more formal wording.
Context: ... Capacity is a parameter (#12), doesn't fix underlying issue Fix: Model the sys...
(FIX_RESOLVE)
skills/systems-thinking/cybernetic-analysis/vsm-guide.md
[style] ~297-~297: The double modal “needed Delayed” is nonstandard (only accepted in certain dialects). Consider “to be Delayed”.
Context: ...ion doesn't reach where it's needed - Delayed: By time information arrives, it's st...
(NEEDS_FIXED)
🪛 markdownlint-cli2 (0.18.1)
skills/systems-thinking/cybernetic-analysis/leverage-points.md
11-11: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
75-75: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
114-114: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
169-169: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
212-212: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
254-254: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
skills/systems-thinking/cybernetic-analysis/SKILL.md
125-125: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
229-229: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
234-234: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
235-235: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
244-244: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
245-245: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
256-256: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
257-257: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
267-267: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
268-268: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
280-280: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
281-281: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
290-290: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
291-291: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
301-301: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
302-302: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
312-312: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
313-313: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
322-322: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
323-323: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
334-334: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
335-335: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (15)
skills/systems-thinking/cybernetic-analysis/leverage-points.md (2)
199-236: Leverage Point #6 (Information Flows) positioning is clear and well-supported.The emphasis on information flows as the highest practical starting point (line 203–208) is pedagogically sound and aligns well with the PR objectives. The concrete software examples (observability, tracing, dashboards) and cost/impact justification make this accessible and actionable. The cross-reference to SKILL.md (line 184 in SKILL.md) correctly directs learners to start here.
408-445: Selection strategy and common mistakes section effectively guides practical application.The structured approach ("Start Here" → "If Those Don't Work" → "Major Changes" → "Transformative") reduces decision fatigue and the common mistakes section preempts anti-patterns. This directly supports the PR objective of helping engineers choose intervention points systematically.
skills/systems-thinking/cybernetic-analysis/vsm-guide.md (3)
11-40: ASCII diagram of VSM clearly illustrates system hierarchy and information flows.The visual structure (Systems 5 → 4 → 3 → 2/3* ↔ 1) makes the nested architecture immediately graspable. This supports the PR objective of making VSM accessible for practical system analysis. The diagram is well-rendered and aligns with Beer's canonical model.
44-79: VSM system descriptions with diagnostic questions provide strong framework for analysis.Each system is clearly defined with actionable diagnostic questions and relatable software examples (microservices, load balancers, SRE teams, etc.). The dysfunctions section preempts common mistakes. This directly supports the four-phase workflow in SKILL.md (lines 101–111) and makes VSM accessible for practical incident investigation and system design.
Also applies to: 82-118, 121-172, 176-215, 219-257
369-396: VSM intervention patterns section aligns well with SKILL.md Phase 4 (Intervention Design).The missing-system and channel-clearing patterns directly map to the patterns in SKILL.md (lines 225–343), providing concrete implementation guidance once dysfunction is identified. Example: "If System 4 missing: Add monitoring, alerting, experimentation" corresponds to visibility-first pattern in SKILL.md.
skills/systems-thinking/cybernetic-analysis/SKILL.md (10)
1-8: YAML front matter is properly formatted with required fields.All required metadata is present (name, description, when_to_use, version, languages, dependencies). The
when_to_usefield concisely covers symptom-driven entry points and explicitly states constraints ("Don't use for greenfield, simple bugs, or unobservable systems"). This aligns well with the four-phase workflow.
43-92: Phase 1 (System Modeling) red flags and mandatory boundary definition prevent premature solutions.Line 51 ("Red flag: 'I already know what to fix' - You don't. Model first.") directly reinforces the PR objective to avoid jumping to interventions. The four modeling steps (boundary, feedback loops, controls, flows) are concrete and map naturally to cybernetic principles. Output specification (system map) provides a tangible deliverable.
93-163: Phase 2 cybernetic analysis applies four lenses systematically.The four lenses (VSM, requisite variety, homeostasis, goal-directed behavior) cover the major frameworks cited in PR objectives. Each lens has concrete assessment questions and dysfunction patterns. The requisite variety section (lines 115–133) correctly frames "variety gap" as fragility indicator. The homeostasis section (lines 135–147) explicitly addresses oscillation (common failure mode). Goal-directed behavior section flags conflicting/vague goals.
Cross-references to @vsm-guide.md (line 103) and leverage points are correct.
165-216: Phase 3 leverage point selection strategy correctly prioritizes information flows (#6) and feedback loops (#8).The strategy prioritizes high-ROI interventions (lines 195–210):
- Start with information flows (cheap, fast, high impact)
- Look for feedback loop opportunities
- Consider structural changes only if above are good
- Question goals/paradigms when lower levels exhaust
This pedagogically guides learners away from low-leverage parameter tweaking (common mistake flagged at line 215). The leverage point hierarchy (lines 175–191) is correct per Meadows, and the cross-reference to @leverage-points.md (line 171) is actionable.
349-364: Quick reference symptom→intervention table bridges theory and practice effectively.The table maps 9 common symptoms to cybernetic causes, first interventions, and leverage points. This supports rapid pattern matching while reinforcing that interventions should flow from analysis (Phase 2→3→4). Example: "Cascading failures" → "Missing negative feedback" → "Circuit breakers, bulkheads" → "#8". This is well-grounded in the frameworks.
Minor note: Verify all symptoms listed here are covered in the detailed phases. (Spot check: cascading failures addressed in Phase 2 VSM/feedback loops, and leverage point #8 is emphasized. ✓)
367-384: Red flags section effectively reinforces mandatory phase sequencing.Lines 367–384 list anti-patterns that indicate skipped analysis:
- "I already know what to fix"
- "This analysis is overkill"
- "Let's just try this and see"
- "We'll adjust the timeout"
- "Obviously we need to..."
Each redirects to Phase 1 (system modeling). This is pedagogically strong and directly prevents the jumping-to-solutions problem the skill is designed to address. The warning about making problems worse (line 383) adds weight.
387-413: Common mistakes section reinforces framework and prevents low-leverage anti-patterns.Five common mistakes are listed with "Why bad" and "Fix" for each:
- Skipping system modeling → missing root causes
- Tweaking parameters → lowest leverage
- Adding features without variety analysis → random accumulation
- Ignoring feedback delays → oscillation
- Treating symptoms → parameters don't address root
Each is well-grounded in the framework (phases and leverage points). The skip-modeling mistake maps to all four phases; others map to specific leverage points or analysis lenses.
416-430: Related skills section clearly positions cybernetic analysis in broader skill ecosystem.The flow (systematic-debugging → root-cause-tracing → Cybernetic System Analysis → architecture/TDD) places this skill after root-cause work but before implementation. The note about "Before applying cybernetics" (line 418) correctly prevents analysis paralysis by anchoring to prior debugging work.
433-448: Remember section and further reading section support skill adoption and deepening.The "Remember" bullets reinforce non-negotiables (model before intervening, use leverage points, requisite variety, feedback loops, set points). The reading list cites all primary sources: Meadows, Beer, Ashby, Wiener, Santa Fe Institute. This demonstrates rigor and enables practitioners to verify frameworks.
1-448: Cross-reference syntax verification needed:@leverage-points.mdand@vsm-guide.md.The SKILL.md file references the other guides via
@leverage-points.md(line 171) and@vsm-guide.md(line 103). These appear to be custom link syntax. Please verify:
- Does the skill repository parser support
@filename.mdsyntax for intra-skill linking?- Should these use standard Markdown relative links instead:
[leverage-points.md](./leverage-points.md)?- Are the paths correct relative to the three files' location in
skills/systems-thinking/cybernetic-analysis/?If
@filename.mdis the repository convention, the references are correct. If not, convert to relative Markdown links for compatibility.
|
Hi! First contribution. Currently applying this skill to some of our system related issues where we combine observability (using Datadog) and our internal systems architecture. Happy to adapt and revise. Thanks! |
1 participant
Add Cybernetic System Analysis Skill
Comprehensive skill for analyzing complex systems using cybernetic principles from pioneers Norbert Wiener, Stafford Beer, W. Ross Ashby, and Donella Meadows.
Overview
Enables systematic analysis of complex systems through a four-phase workflow:
Use Cases
Files
Key Frameworks
Testing & Validation
TDD for Documentation approach:
Baseline (RED): Tested 3 scenarios WITHOUT skill
With Skill (GREEN): Retested with skill present
Iteration (REFACTOR): No loopholes found - skill is bulletproof on first iteration
Example Usage
Agent will:
Discovery Optimization
when_to_use: Optimized for symptom-based discovery:
Keywords: feedback loops, VSM, requisite variety, leverage points, homeostasis, viable systems model, cybernetics
Related Work
This skill complements:
systematic-debugging- Find root causes before systemic analysisroot-cause-tracing- Trace bugs deep in execution🤖 Generated with Claude Code
Co-Authored-By: Claude [email protected]
Summary by CodeRabbit