@event4u/agent-config 1.31.0 → 1.33.0

package/docs/guidelines/agent-infra/six-hats.md

@@ -0,0 +1,353 @@
+# Six Thinking Hats
+
+Reference guideline for Wing-1 deep-thinking work — Edward de Bono's
+six-perspective method for examining ideas through Facts · Feelings ·
+Cautions · Benefits · Creativity · Process — one hat at a time, to
+separate thinking modes and avoid the cross-talk that derails group
+decisions. Adopted under the **Reference-Guideline Sunset Policy** and
+cross-referenced from:
+
+- [`deep-reading-analyst`](../../../.agent-src.uncompressed/skills/deep-reading-analyst/SKILL.md)
+  — L2 Standard analysis depth (multi-perspective sweep).
+- [`ai-council`](../../../.agent-src.uncompressed/skills/ai-council/SKILL.md)
+  — multi-model consultation pattern; Six Hats is the per-perspective
+  decomposition the council voices use when adjudicating a decision.
+- [`/council`](../../../.agent-src.uncompressed/commands/council.md)
+  — internal council orchestrator routing to per-hat persona prompts.
+
+> **Core principle:** "Wear one hat at a time." — separating thinking
+> modes reduces conflict and ensures comprehensive coverage of facts,
+> emotions, risks, value, alternatives, and meta-process.
+
+## When to Use
+
+Ideal for:
+
+- Multi-perspective decision review without role-locking
+- Group sessions where parallel thinking is needed
+- Avoiding the "this is good but risky" mode-mixing trap
+- Pre-mortem on a plan when [`inversion-thinking`](inversion-thinking.md)
+  is too narrow (Black hat alone) and you want all six lenses
+
+Do **not** use when the user wants depth on a single dimension (use
+[`mental-models`](mental-models.md)) or a structured decision artifact
+(use [`scqa-framework`](scqa-framework.md)).
+
+## The Six Hats
+
+### White Hat — Facts & Data
+
+**Focus:** objective information only.
+
+**Questions:**
+
+- What facts do we have?
+- What data is available?
+- What information is missing?
+- What are the numbers?
+- How do we verify this?
+
+**Language:** "According to…", "The data shows…", "We know that…",
+"We don't know…".
+
+**In content analysis:** extract factual claims · note cited sources ·
+identify missing data · separate facts from interpretations.
+
+**Template:**
+
+```markdown
+## Known Facts
+- [Verifiable fact 1]
+- [Verifiable fact 2]
+
+## Missing Information
+- [ ] [Gap 1]
+- [ ] [Gap 2]
+
+## Data Sources
+- [Citation 1]: [Quality rating]
+```
+
+### Red Hat — Emotions & Intuition
+
+**Focus:** gut feelings, hunches, intuitive responses.
+
+**Questions:**
+
+- What's my immediate reaction?
+- What does my gut say?
+- What emotions does this evoke?
+- What's my intuition telling me?
+
+**Language:** "I feel that…", "My gut says…", "This makes me
+uncomfortable because…", "I'm excited about…".
+
+**In content analysis:** note emotional response while reading ·
+identify what triggers strong feelings · trust instincts about
+credibility · recognize persuasive emotional appeals in text.
+
+**Template:**
+
+```markdown
+## Immediate Reactions
+- [Emotion] at [specific part]
+
+## Gut Feelings
+- Something feels off about: [intuition]
+- Exciting / Compelling: [what resonates]
+
+## Emotional Triggers in Text
+- Author uses [emotion] to persuade
+```
+
+**Important:** no justification needed. Pure feeling.
+
+### Black Hat — Caution & Risks
+
+**Focus:** critical judgment, potential problems.
+
+**Questions:**
+
+- What could go wrong?
+- What are the risks?
+- What's unrealistic?
+- Where's the weakness?
+- What are the downsides?
+
+**Language:** "A problem is…", "This won't work because…", "The risk
+here is…", "We're overlooking…".
+
+
+**In content analysis:** identify logical flaws · note unsupported
+claims · point out potential failures · question feasibility ·
+consider unintended consequences.
+
+**Template:**
+
+```markdown
+## Logical Weaknesses
+- [Flaw 1] in reasoning
+
+## Risks If Applied
+- Risk: [consequence]
+- When it fails: [scenario]
+
+## Missing Considerations
+- Doesn't account for: [factor]
+
+## Overly Optimistic Claims
+- [Claim] seems unrealistic because [reason]
+```
+
+**Important:** critical, not cynical. Necessary for risk assessment.
+
+### Yellow Hat — Benefits & Optimism
+
+**Focus:** positive aspects, value, opportunities.
+
+**Questions:**
+
+- What's the value here?
+- What are the benefits?
+- Why would this work?
+- What's the best-case scenario?
+- What opportunities does this create?
+
+**Language:** "The benefit is…", "This could work because…", "The
+value here is…", "An opportunity is…".
+
+**In content analysis:** extract valuable insights · identify strong
+arguments · note practical applications · find novel perspectives ·
+recognize what advances the field.
+
+**Template:**
+
+```markdown
+## Key Value Propositions
+- Valuable insight: [what's useful]
+
+## Strong Points
+- Well-supported: [argument]
+
+## Potential Applications
+- Could be used for: [use case]
+
+## Novel Contributions
+- New perspective on: [topic]
+
+## Best-Case Outcome
+If fully applied: [positive scenario]
+```
+
+**Important:** be realistic but generous. Find genuine value.
+
+### Green Hat — Creativity & Alternatives
+
+**Focus:** new ideas, possibilities, innovations.
+
+**Questions:**
+
+- What else is possible?
+- How else could we think about this?
+- What's a creative alternative?
+- What if we combined X with Y?
+- What's unconventional?
+
+**Language:** "What if…", "Another way to look at it…", "We could
+also…", "An alternative is…".
+
+**In content analysis:** extend the author's ideas further · generate
+alternatives to proposed solutions · combine with other frameworks ·
+apply to new domains · challenge assumptions creatively.
+
+**Template:**
+
+```markdown
+## Extensions of Ideas
+- Taking [concept] further: [new application]
+
+## Alternative Approaches
+Instead of [author's method], what if: [alternative]
+
+## Creative Combinations
+- [Idea from text] + [other framework] = [new insight]
+
+## Unconventional Applications
+- Apply this to [unexpected domain]
+
+## "What If" Scenarios
+- What if [assumption] were reversed?
+```
+
+**Important:** no criticism in green-hat mode. All ideas welcome.
+
+### Blue Hat — Process & Meta-Thinking
+
+**Focus:** managing thinking, overview, conclusions.
+
+**Questions:**
+
+- What have we covered?
+- What thinking mode do we need now?
+- What's the summary?
+- What's next?
+- How should we think about this?
+
+**Language:** "We've covered…", "The next step is…", "In summary…",
+"We need to focus on…".
+
+**In content analysis:** decide which hats to use when · synthesize
+findings from all hats · determine next steps · plan learning
+strategy · monitor the analysis process.
+
+**Template:**
+
+```markdown
+## Analysis Process
+1. White: Gathered facts
+2. Red: Noted reactions
+3. Black: Identified risks
+4. Yellow: Found value
+5. Green: Generated alternatives
+
+## Synthesis
+Combining all perspectives:
+- [Integrated insight]
+
+## Next Steps
+- [ ] Further research: [area]
+- [ ] Practical test: [action]
+- [ ] Deep dive: [topic]
+
+## Time Investment
+Worth [X] time because [reason]
+```
+
+**Important:** Blue hat organizes the other hats. It's the conductor.
+
+## Usage Patterns
+
+| Pattern | Sequence |
+|---|---|
+| **Quick evaluation (15 min)** | White → Red → Yellow → Black → Blue |
+| **Deep analysis (60 min)** | White → Red → Black → Yellow → Green → Blue → revisit any → Blue |
+| **Problem-solving** | White → Red → Green → Yellow → Black → Green → Blue |
+| **Decision-making** | White → Yellow → Black → Red → Blue |
+
+## Rules of Engagement
+
+1. **One hat at a time** — don't mix modes.
+2. **Everyone wears the same hat** — parallel thinking (if group).
+3. **Separate person from hat** — you're not "the critical person",
+   you're wearing the Black hat.
+4. **Time-box** — set limits per hat.
+5. **Blue hat controls** — decides sequence and timing.
+
+## Common Mistakes
+
+- ❌ **Mixing hats** — *"This is good (yellow) but risky (black)."*
+  ✅ **Separate:** Yellow session: *"This is good because X."* Then
+  Black session: *"The risk is Y."*
+- ❌ **Judging feelings** — *"That's irrational"* during Red hat.
+  ✅ **Accept feelings:** all emotions noted without judgment.
+- ❌ **Weak yellow** — *"I guess there's some value…"*.
+  ✅ **Genuine optimism:** really find the good.
+- ❌ **Staying too long** — 30 min per hat.
+  ✅ **Move on:** 5–10 min per hat is usually sufficient.
+
+## Application to Reading
+
+**When to use which hat:**
+
+- **Understanding stage:** White (facts), Red (reactions).
+- **Evaluation stage:** Black (critique), Yellow (value).
+- **Application stage:** Green (ideas), Blue (synthesis).
+
+**Full cycle:**
+
+1. White: what does the text actually say?
+2. Red: how do I feel about it?
+3. Black: what's wrong with it?
+4. Yellow: what's right with it?
+5. Green: what else could we do with this?
+6. Blue: so what? Now what?
+
+## Integration with Other Frameworks
+
+- **After [`first-principles`](first-principles.md):** use hats to
+  evaluate the rebuilt argument.
+- **After [`systems-thinking`](systems-thinking.md):** use Yellow /
+  Black on leverage points.
+- **Before [`critical-thinking`](critical-thinking.md):** use Red to
+  surface biases.
+- **During synthesis:** use Blue to organize findings.
+
+## Output Format
+
+```markdown
+# Six Hats Analysis: [Content Title]
+
+## White: Facts
+[Objective data]
+
+## Red: Feelings
+[Emotional response]
+
+## Black: Cautions
+[Risks and weaknesses]
+
+## Yellow: Benefits
+[Value and opportunities]
+
+## Green: Possibilities
+[Creative extensions]
+
+## Blue: Conclusions
+[Synthesis and next steps]
+```
+
+---
+
+## ADOPT citation
+
+Adopted from [`ginobefun/deep-reading-analyst-skill`](https://github.com/ginobefun/deep-reading-analyst-skill) @ commit `26cd7dc9` · `src/deep-reading-analyst/references/six_hats.md` · MIT License.

package/docs/guidelines/agent-infra/systems-thinking.md

@@ -0,0 +1,220 @@
+# Systems Thinking
+
+Reference guideline for Wing-1 deep-thinking work — Donella Meadows'
+parts-and-relationships lens. Understand a system by mapping
+components, interconnections, purpose, and boundaries; then trace
+feedback loops, leverage points, and cross-domain archetypes that
+reveal where intervention has the highest impact. Adopted under the
+**Reference-Guideline Sunset Policy** and cross-referenced from:
+
+- [`deep-reading-analyst`](../../../.agent-src.uncompressed/skills/deep-reading-analyst/SKILL.md)
+  — L3 Deep analysis depth.
+- [`mental-models`](mental-models.md) — Munger's lattice; systems
+  thinking is one of the strongest engineering / biology lenses.
+- [`first-principles`](first-principles.md) — pairs with system
+  rebuild after assumption strip.
+- [`six-hats`](six-hats.md) — apply Yellow / Black on identified
+  leverage points.
+
+> **Core principle:** "The system is more than the sum of parts."
+> — Donella Meadows. Behavior emerges from interactions, not
+> components.
+
+## Key System Elements
+
+1. **Components (elements)** — the individual parts of the system.
+2. **Relationships (interconnections)** — how components influence
+   each other.
+3. **Purpose (function)** — what the system is designed to achieve.
+4. **Boundaries** — what's inside vs. outside the system.
+
+## Causal Loop Analysis
+
+### Reinforcing loop (positive feedback)
+
+Creates exponential growth or collapse.
+
+```
+A increases → B increases → A increases further → ...
+```
+
+**Examples:**
+
+- Network effects: more users → more value → more users.
+- Panic: fear → selling → price drop → more fear.
+- Expertise: skill → opportunities → more practice → more skill.
+
+**Symbol:** R (Reinforcing).
+
+### Balancing loop (negative feedback)
+
+Creates stability and resistance to change.
+
+```
+A increases → B increases → A decreases → B decreases → ...
+```
+
+**Examples:**
+
+- Thermostat: temp up → heating off → temp down → heating on.
+- Supply / demand: price up → demand down → price down.
+- Homeostasis: blood sugar up → insulin up → blood sugar down.
+
+**Symbol:** B (Balancing).
+
+## Mapping Template
+
+```markdown
+## System Components
+- Component A: [Role / function]
+- Component B: [Role / function]
+- Component C: [Role / function]
+
+## Key Relationships
+
+[A] ──+──> [B]  (A increases B)
+       |
+       └──-──> [C]  (A decreases C)
+
+## Feedback Loops
+
+### Loop 1: [Name] (R / B)
+A → B → C → A
+Effect: [Exponential growth / Stabilization]
+
+## System Behavior Over Time
+
+Current state: [X]
+If X increases: [Trace effects through system]
+If X decreases: [Trace effects through system]
+```
+
+## Leverage Points
+
+Donella Meadows' hierarchy, strongest to weakest:
+
+1. **Paradigms** — mental models underlying the system.
+2. **Goals** — purpose of the system.
+3. **System structure** — feedback loop architecture.
+4. **Delays** — response time between cause and effect.
+5. **Balancing loops** — strength of stabilizing forces.
+6. **Reinforcing loops** — strength of amplifying forces.
+7. **Information flows** — who knows what, when.
+8. **Rules** — incentives, constraints.
+9. **Buffers** — stabilizing stocks.
+10. **Stock-flow structures** — physical components.
+11. **Parameters** — numbers (least effective).
+
+**Insight:** most people tweak parameters (#11), but changing
+paradigms (#1) is far more powerful.
+
+
+## Cross-Domain Pattern Recognition
+
+### Tragedy of the Commons
+
+- Environment: overfishing.
+- Digital: bandwidth congestion.
+- Social: public resource depletion.
+- Organizational: shared resource competition.
+
+### Network Effects
+
+- Technology: social media platforms.
+- Economics: currency adoption.
+- Language: English as lingua franca.
+- Standards: USB-C adoption.
+
+### Limits to Growth
+
+- Biology: population dynamics.
+- Business: market saturation.
+- Personal: skill plateaus.
+- Resources: oil production peak.
+
+## Analysis Questions
+
+### Structure
+
+- What are the key components?
+- What connects them?
+- Where are the feedback loops?
+
+### Behavior
+
+- What patterns emerge over time?
+- What's amplifying? (reinforcing loops)
+- What's stabilizing? (balancing loops)
+
+### Dynamics
+
+- What happens if X increases 10x?
+- Where are delays causing problems?
+- What's the bottleneck?
+
+### Boundaries
+
+- What's outside this system but affects it?
+- Where do we draw the line?
+- What external factors matter?
+
+## Systems Archetypes
+
+| Archetype | Pattern | Example |
+|---|---|---|
+| **Shifting the burden** | Short-term fix undermines long-term solution | Painkillers (symptom) vs. fixing posture (cause) |
+| **Escalation** | Both sides respond to each other, spiraling up | Arms race · price wars · social-media arguments |
+| **Success to the successful** | Winner gets compounding advantages | Bestseller lists · platform dominance |
+| **Fixes that fail** | Initial solution creates worse problem | Antibiotic resistance · induced traffic demand |
+| **Growth and underinvestment** | Growth stalls because capacity wasn't built | Startup success → can't scale → service degrades |
+
+## Application to Content Analysis
+
+When reading about any topic:
+
+1. **Map the system** — list elements mentioned, draw connections.
+2. **Identify loops** — what reinforces growth / decline? what
+   creates balance / limits?
+3. **Predict dynamics** — if X changes, what cascades follow? where
+   in 1 year? 5 years?
+4. **Find leverage** — where is the author intervening? are there
+   better leverage points?
+5. **Connect to other domains** — what similar patterns exist
+   elsewhere? can solutions from other fields apply?
+
+## Cross-Domain Analysis Template
+
+```markdown
+## Concept in Article
+[Core idea from content]
+
+## Similar Patterns In:
+
+**Economics:**  [How this shows up]
+**Biology:**    [How this shows up]
+**Psychology:** [How this shows up]
+**Technology:** [How this shows up]
+**History:**    [How this shows up]
+
+## Transferable Insights
+If this pattern exists across domains, then:
+- [Universal principle 1]
+- [Universal principle 2]
+```
+
+## Pitfalls
+
+- **Over-complicating** — not everything needs a full system map.
+- **Analysis paralysis** — perfect map vs. good-enough understanding.
+- **Ignoring human agency** — people can change system rules.
+- **Determinism** — systems have probability, not certainty.
+- **Closed thinking** — real systems have open boundaries.
+
+**Balance:** use systems thinking to understand dynamics, not to
+predict perfectly.
+
+---
+
+## ADOPT citation
+
+Adopted from [`ginobefun/deep-reading-analyst-skill`](https://github.com/ginobefun/deep-reading-analyst-skill) @ commit `26cd7dc9` · `src/deep-reading-analyst/references/systems_thinking.md` · MIT License.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.31.0",
+    "version": "1.33.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/check_bite_sized_granularity.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Bite-sized task granularity gate for structural roadmaps (P1.5).
+
+Adopted from `obra/superpowers` `writing-plans/SKILL.md` § Task Structure +
+§ No Placeholders (v5.1.0). Complexity-gating is our addition (Council
+Round 1, Q4) — only roadmaps tagged `complexity: structural` in frontmatter
+are subject to the granularity rules; `complexity: lightweight` skips.
+
+Public API (stdlib-only):
+
+    read_complexity(text)            -> 'structural' | 'lightweight' | None
+    scan_placeholders(text)          -> list[Placeholder]
+    check_granularity(text)          -> Result(complexity, gated, violations)
+
+`gated` is True only when `complexity == 'structural'`. Violations are
+empty when the gate is not active, regardless of placeholder presence.
+
+The CI contract for P1.5 is the pytest harness in
+`tests/test_bite_sized_granularity.py`; this module is the test surface.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+PLACEHOLDER_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = (
+    ("angle-placeholder", re.compile(r"<[a-z][a-z0-9 _\-/]*>", re.IGNORECASE)),
+    ("todo", re.compile(r"\bTODO\b")),
+    ("fixme", re.compile(r"\bFIXME\b")),
+    ("xxx", re.compile(r"\bXXX\b")),
+    ("tbd", re.compile(r"\btbd\b", re.IGNORECASE)),
+    ("triple-question", re.compile(r"\?\?\?")),
+)
+
+COMPLEXITY_PAT = re.compile(
+    r"^complexity:\s*(lightweight|structural)\s*$", re.MULTILINE
+)
+
+
+@dataclass(frozen=True)
+class Placeholder:
+    kind: str
+    line: int
+    text: str
+
+
+@dataclass
+class Result:
+    complexity: str | None
+    gated: bool
+    violations: list[Placeholder] = field(default_factory=list)
+
+
+def _frontmatter(text: str) -> str:
+    if not text.startswith("---\n"):
+        return ""
+    end = text.find("\n---\n", 4)
+    return text[4:end] if end != -1 else ""
+
+
+def read_complexity(text: str) -> str | None:
+    """Return the `complexity:` value from the roadmap frontmatter, or None."""
+    fm = _frontmatter(text)
+    if not fm:
+        return None
+    m = COMPLEXITY_PAT.search(fm)
+    return m.group(1) if m else None
+
+
+def scan_placeholders(text: str) -> list[Placeholder]:
+    """Return every placeholder hit in task-bullet lines (`- [ ]` / `- [x]`)."""
+    hits: list[Placeholder] = []
+    for line_no, line in enumerate(text.splitlines(), start=1):
+        stripped = line.lstrip()
+        if not stripped.startswith(("- [ ]", "- [x]", "- [/]", "- [-]")):
+            continue
+        for kind, pat in PLACEHOLDER_PATTERNS:
+            if pat.search(line):
+                hits.append(Placeholder(kind=kind, line=line_no, text=line.rstrip()))
+                break
+    return hits
+
+
+def check_granularity(text: str) -> Result:
+    """Run the granularity gate.
+
+    Structural roadmaps fail on any placeholder hit in task bullets.
+    Lightweight or untagged roadmaps skip the gate (gated=False) and
+    return an empty violation list even when placeholders are present.
+    """
+    complexity = read_complexity(text)
+    gated = complexity == "structural"
+    if not gated:
+        return Result(complexity=complexity, gated=False, violations=[])
+    return Result(
+        complexity=complexity,
+        gated=True,
+        violations=scan_placeholders(text),
+    )