systems-thinking
Skill1 starsChanged 2 months agoMITView on GitHub
Architectural analysis using Feedback Loops and System Dynamics. Use when designing architectures, scaling systems, or analyzing side effects.
10 other projects use a version of this.
Adopted by
Most recently taken up by
- itsmostafa/agent-skillstheir own version, first seen Nov 11, 2026
- ironyjk/strategy-frameworkstheir own version, first seen Oct 17, 2026
- fzfclee/consulting-skillstheir own version, first seen Oct 13, 2026
- ysskrishna/ai-agent-skillstheir own version, first seen Oct 13, 2026
- mlevison/agent-thinking-skillstheir own version, first seen Oct 7, 2026
- docxology/codomyrmextheir own version, first seen Oct 6, 2026
Other versions10 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 10
- ysskrishna/ai-agent-skills★ 25same name
- mlevison/agent-thinking-skills★ 18same name
- ironyjk/strategy-frameworks★ 14same name
- docxology/codomyrmex★ 11same name
- fzfclee/consulting-skills★ 6same name
- itsmostafa/agent-skills★ 4same name
- rcdelfin/agentkit★ 2same name
- younss/skills★ 1same name
- dhriyatinandu-bot/claude-skills★ 0same name
- vbrevik/claude_code_skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository10 other files it gives its agents.
- chestertons-fenceSkill
- decision-matrixSkill
- first-principles-thinkingSkill
- humanizer-karu-customSkill
- inversion-thinkingSkill
- map-vs-territorySkill
- occams-razorSkill
- pareto-principleSkill
- rubber-duckingSkill
- second-order-thinkingSkill
The file
We split this skill into the rules it gives an agent
9 rules. 0 are common, 9 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 9 edited versions we read keep these.
9
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 29
Stop thinking in Lines (Problem -> Solution).
- Distinctive: line 30
Start thinking in Loops (Action -> Result -> Feedback -> Action).
- Distinctive: line 42
Node Discovery: Ask "What does this component talk to?" — trace data flow, not code structure.
- Distinctive: line 49
Hidden Edge Hunt: Ask "What has broken in production that nobody predicted?" — force confrontation with unmapped dependencies.
- Distinctive: line 75
Do not guess. Look for evidence.
- Distinctive: line 76
Log Analysis: Look at past logs. Did similar changes cause latency spikes?
- Distinctive: line 84
If you can't say it plainly, you don't understand the loop.
- Distinctive: line 87
Ask for each loop identified:
- Distinctive: line 163
Pass criteria: Does not over-engineer analysis for trivial change.
“Common” is measured: kept by at least 6 in 10 of the 9 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Systems Thinking (The Loop Protocol)
"You cannot just change one thing." - Garrett Hardin
When to Use
- Architecture Changes: Migrating DBs, splitting microservices, changing cache strategies.
- Scaling: "We need to handle 10x traffic."
- Performance Tuning: "The system is slow, let's add threads."
- Post-Mortems: "Why did fixing X break Y?"
- Adding new services that touch shared resources.
When NOT to Use
- Simple, isolated changes — single function, known system, no shared state.
- Well-understood systems with < 5 connected components — use simplified trace only.
- Time-critical decisions — loop analysis takes longer than linear analysis.
- Experimental/prototype code — where failure is expected and recovery is cheap.
- Greenfield projects — no loops exist yet to analyze.
The Protocol: The Loop Protocol
Stop thinking in Lines (Problem -> Solution). Start thinking in Loops (Action -> Result -> Feedback -> Action).
Protocol Triage
Match rigor to risk:
- Simplified (fast): Known system, < 5 components, reversible change → Steps 1-2 only.
- Full (thorough): Novel architecture, post-mortem, irreversible change → All steps.
1. Identify the Node
What variable are you changing?
- Example: "I am increasing the Thread Pool size."
Node Discovery: Ask "What does this component talk to?" — trace data flow, not code structure.
2. Trace the Edges
What is connected to this node?
- Downstream: Threads consume -> DB Connections.
- Upstream: Threads process -> Incoming Requests.
Hidden Edge Hunt: Ask "What has broken in production that nobody predicted?" — force confrontation with unmapped dependencies.
3. Find the Loops
Loop Priority (Analyze in Order):
- Reinforcing loops (R) — Explosion risk. Short delay makes these dangerous.
- Balancing loops (B) — Bottleneck risk. Protect critical resource limits.
- Delay-heavy loops — Silent accumulation risk. Problems manifest long after cause.
Reinforcing Loop (R): Does A produce more B, which produces more A?
- Example: Retry Logic. Fails -> Retry -> More Load -> Fails.
- Saboteur Mode: "If I wanted this to fail catastrophically, what would I amplify?"
Balancing Loop (B): Does A produce B, which reduces A?
- Example: Auto-scaling. Load High -> Add Servers -> Load per Server Low -> Remove Servers.
Delay Effect: Does change take time to manifest?
- Example: Cache warming, connection pool exhaustion, resource leaks.
3.5. R-Loop Safeguard Gate (Inline)
[!IMPORTANT] CRITICAL: If a reinforcing loop (R) with short delay is found in Step 3, MUST propose a safeguard before proceeding to Step 4. Unchecked R-loops cause cascading failures.
Record the safeguard alongside the loop in the Loops Inventory (see Step 7).
4. Validation (The Pre-Mortem)
Do not guess. Look for evidence.
- Log Analysis: Look at past logs. Did similar changes cause latency spikes?
- Trade-off Question: "If I maximize X, what must decrease?" (e.g., Speed vs Memory).
- Drift Test: "If we do this 1000 times a second, what breaks?"
5. Duck Translation
Explain each loop in one sentence:
"The [NODE] causes [EDGE], which causes [NODE], which [INCREASES/DECREASES] the original."
If you can't say it plainly, you don't understand the loop.
6. Second-Order Effects Check
Ask for each loop identified:
- Does this loop affect other loops?
- Does success here create conditions for failure elsewhere?
- Does removing this loop create a new reinforcing loop?
Stop Conditions
Stop analysis when:
- You've identified all loops connecting to the change
- Additional nodes reveal no new edges
- You've hit an emergence boundary — nodes interact to produce behavior none have alone
- Time spent exceeds value of further analysis (Pareto: 80% of insights from 20% of loops)
|-------|---------------|
| chestertons-fence | Before removing any node — verify it's not load-bearing |
| occams-razor | After systems-thinking: if no loops involve this component, simplification is safer |
| inversion-thinking | For each R-loop, ask "How do I amplify this failure?" |
| second-order-thinking | Trace cascades beyond immediate loop effects |
| decision-matrix | When criteria become circular — collapse into meta-criteria |
| rubber-ducking | When loop explanation doesn't sound right in plain English |
Common Chain: systems-thinking → occams-razor (simplify what isn't load-bearing) → chestertons-fence (verify before removing)
Self-Improvement Protocol
Log only surprises — unintended consequences, loop behavior different than predicted, missed dependencies.
## [YYYY-MM-DD] {system} → {loop type} → {predicted} vs {actual}Promote after 3+ similar discoveries.
Pattern Categories (Prioritized)
High-Risk (Analyze First):
- Reinforcing loops with short delays (explosion risk)
- Balancing loops protecting critical resources (bottleneck risk)
- Shared state mutations
Medium-Risk (Verify):
- Delay-heavy loops (silent accumulation)
- External service dependencies
- Caching layers
Low-Risk (Acknowledge):
- Well-isolated components
- Read-only operations
- Replicated services
Resources
- Detailed Research Notes
- System Archetypes Reference
Evaluations
Eval 1: Retry Loop Explosion Detection
Scenario: Adding retry logic to failed API calls. Service has 500ms timeout. Expected: Identifies reinforcing loop: Fail -> Retry -> More Load -> Fail. Recognizes short delay makes this dangerous. Pass criteria: MUST identify retry storm as R-loop, suggests exponential backoff as countermeasure.
Eval 2: Hidden Dependency Discovery
Scenario: User wants to "just increase the thread pool size" in a Java app. Expected: Traces edges to DB connections, identifies balancing loop: Threads -> DB Connections -> Thread contention. Pass criteria: Discovers hidden dependency on connection pool, not just thread count.
Eval 3: Simplified Protocol Triage
Scenario: User wants to refactor a single utility function with no shared state. Expected: Applies triage: < 5 components, no shared state, applies simplified (Steps 1-2 only). Pass criteria: Does not over-engineer analysis for trivial change.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

