@event4u/agent-config 14.23.0 → 16.0.0

package/dist/agent-src/guidelines/agent-infra/memory-access.md

@@ -0,0 +1,149 @@
+# Memory Access
+
+How a skill or command reads engineering memory. Memory is entirely
+**file-backed** (`agents/memory/`); there is no external backend.
+
+Single entry point: the shared `retrieve(types, keys, limit)`
+abstraction backed by `scripts/memory_lookup.ts` (TypeScript, run via
+tsx). It reads curated YAML under `agents/memory/<type>/` and the
+agent-written `agents/memory/intake/*.jsonl` signal log.
+
+## Index by the moment, not only by the topic
+
+Every entry answers **"what was I about to do when this would have helped"** — a
+verb and its object (`author a roadmap`, `wait on CI`, `push a branch`, `edit a
+markdown section with a script`) — and the index carries a trigger-moment
+section keyed on those verbs beside the topic grouping.
+
+A store indexed only by subject is an index for *browsing*, and browsing is not
+the failure mode: an agent does not go looking for a trap it does not know
+exists. Measured 2026-08-20 on one instrumented session — of eleven error
+classes, **nine already had an entry** and all nine were read *after* the
+failure. The deficit was delivery, not knowledge.
+
+Writing the trigger key is part of writing the entry. A second index maintained
+separately from the entries rots, and a rotted index is worse than none because
+it still looks authoritative.
+
+## The contract
+
+Consumers reach it via the CLI (`agent-config memory:lookup`) or the
+MCP `memory_lookup` tool — never by ad-hoc file reads:
+
+```bash
+agent-config memory:lookup \
+  --types ownership,historical-patterns \
+  --key "app/Http/Controllers/Billing/Checkout.php" \
+  --limit 3
+# --key is repeatable; add --format json for the raw hits,
+# --envelope v1 for the retrieval-contract envelope.
+```
+
+**Index-first discipline** (road-to-memory-retrieval-economy — the mirror
+of the MCP tool descriptions, for hosts without MCP): when you expect more
+hits than you need, look up with `--envelope v1 --detail index` first —
+each row carries `id`, `title` and `tokens_estimate` (the cost of fetching
+it) — then fetch ONLY the ids you will actually use via the `memory_get`
+MCP tool (or a full `--detail full` lookup narrowed to the right keys),
+batching multiple ids into one call. For precise single-hit lookups the
+full envelope is already minimal — the paired measurement showed index-
+first COSTS tokens there (honest null pinned in
+`internal/bench/reports/memory-retrieval-run.json`), so reach for index
+mode on broad or exploratory queries, not reflexively.
+
+Every backend MUST return a list of `Hit` with:
+
+| Field | Meaning |
+|---|---|
+| `id` | Stable identifier |
+| `type` | One of the curated types (`ownership`, `historical-patterns`, `domain-invariants`, `incident-learnings`, `product-rules`) |
+| `source` | `"curated"` or `"intake"` |
+| `path` | File or logical source that produced the hit |
+| `score` | Float in `[0..1]`; higher is better |
+| `entry` | Full decoded entry — skills read what they need |
+
+Skills treat `source: "curated"` as higher-trust and `source: "intake"`
+as provisional (best-effort, agent-written, not human-reviewed).
+
+**Sharing boundary.** Curated YAML (`agents/memory/<type>/*.yml`) is
+**committed** — it is the team-shared layer. Raw intake
+(`agents/memory/intake/*.jsonl`) is **gitignored, local scratch** in a
+consumer project — only entries promoted to curated get shared. `retrieve()`
+still reads local intake (low-confidence tier); it just never reaches the team
+repo unpromoted.
+
+> **Which repo you are in changes this one line.** In a **consumer project**
+> intake is gitignored — the shipped block in `src/config/gitignore-block.txt`
+> lists `/agents/memory/intake/`. In **this package's own repo** it is
+> **tracked** and union-merged, because here intake is part of the corpus
+> under test; `agents/memory/intake/README.md` says so ("Local + tracked").
+> Both are correct in their own context, and the sentence above states the
+> consumer one. Read unconditionally, it makes a maintainer treat tracked
+> intake files as a mistake, and it makes a consumer who follows the
+> directory's README commit raw signals by accident.
+
+## The status helper
+
+`scripts/memory_status.ts` exports `status()`, reporting the (constant)
+file backend so consumers — including the MCP `memory_status` tool and
+the v1 health envelope — read a stable shape:
+
+```ts
+import { status } from './memory_status.js';
+const r = status(); // constant; file-backed, never raises
+// r.status === 'file' && r.backend === 'file'
+```
+
+Contract guarantees:
+
+- **Never raises** — `status()` is side-effect-free and constant.
+- **Stable** — the four fields (`status`, `backend`, `reason`,
+  `elapsed_ms`) never change shape between releases.
+
+## How skills should use it
+
+1. **Call the abstraction.** Skills use `retrieve()`, not ad-hoc file
+   reads, so the supersede-chain and ranking semantics stay intact.
+2. **Cap the load.** Respect `memory.retrieval.max_entries_per_task`
+   from `.agent-project-settings`. Over-retrieval pollutes the context
+   window without improving answers.
+3. **Log the source in the reply.** A reviewer skill citing memory
+   should say "per `ownership:team-payments` (curated) at
+   `agents/memory/ownership.yml:42`" — the reader verifies cheaply.
+4. **Treat intake as low-confidence.** Only promote intake findings
+   into the final reply when the user can act on them; otherwise keep
+   them as internal context.
+
+## Access policy per role mode
+
+Echoes `memory.retrieval.auto_load_shared_types` in
+`.agent-project-settings`:
+
+| Role mode | Auto-loaded types |
+|---|---|
+| Developer | `domain-invariants`, `ownership` |
+| Reviewer | `ownership`, `historical-patterns`, `incident-learnings` |
+| Tester | `historical-patterns`, `incident-learnings` |
+| PO / planner | `product-rules` |
+| Incident | `incident-learnings`, `ownership` |
+
+Other types remain accessible on demand via
+`/memory-full <type>` (not a skill choice).
+
+## Anti-patterns
+
+- **Do NOT** read `agents/memory/**` directly with ad-hoc globbing.
+  Skills lose the supersede-chain semantics and the `merge=union`
+  guarantees. Always go through `retrieve()`.
+- **Do NOT** cache hits across sessions. Curated files change between
+  reads; re-run `retrieve()` each time.
+- **Do NOT** fall back to intake JSONL when the curated file *exists
+  but is empty*. That is a valid "no entries" answer, not a fallback
+  signal.
+
+## See also
+
+- [`engineering-memory-data-format.md`](engineering-memory-data-format.md)
+  — the on-disk schema
+- [`../../rules/context-hygiene.md`](../../rules/context-hygiene.md)
+  — token budget that `max_entries_per_task` protects

package/dist/agent-src/guidelines/agent-infra/mental-models.md

@@ -0,0 +1,314 @@
+# Mental Models
+
+Reference guideline for Wing-1 deep-thinking work — Charlie Munger's
+multi-discipline lattice for analyzing problems through more than one
+lens at a time. Adopted under the **Reference-Guideline Sunset Policy**
+(see frontmatter `upstream` / `refresh_trigger` keys) and cross-referenced
+from:
+
+- [`deep-reading-analyst`](../../skills/deep-reading-analyst/SKILL.md)
+  — L3 Deep analysis depth.
+- [`refine-prompt`](../../skills/refine-prompt/SKILL.md)
+  — multi-lens prompt refinement.
+- [`judge-bug-hunter`](../../skills/judge-bug-hunter/SKILL.md)
+  — diff review through more than the bug-hunter lens.
+
+> **Core principle:** "To a man with only a hammer, every problem looks
+> like a nail." — Charlie Munger
+
+## When to Use
+
+Ideal for:
+- 📊 Understanding complex problems from multiple angles
+- 🔍 Avoiding cognitive biases and blind spots
+- 💡 Finding innovative solutions
+- 🎯 Making important decisions
+- 📚 Cross-disciplinary learning and knowledge integration
+
+## Core Mental Models Toolkit
+
+### 1. General Thinking Models
+
+#### First Principles
+- Strip away assumptions to fundamentals
+- Rebuild from basic truths
+- Application: Analyze article's core assumptions
+
+#### Compounding
+- Long-term accumulation creates exponential growth
+- Small improvements compound over time
+- Application: Evaluate long-term strategies in content
+
+#### Opportunity Cost
+- Choosing one option means forgoing others
+- Evaluate trade-offs
+- Application: Analyze the cost of recommended approaches
+
+### 2. Physics Models
+
+#### Leverage
+- Small force creates large results
+- Find the critical leverage points
+- Application: Identify key action points in articles
+
+#### Inertia
+- Systems tend to maintain current state
+- Change requires additional energy
+- Application: Understand resistance to change
+
+#### Critical Mass
+- Qualitative change occurs after reaching threshold
+- Accumulation to breakthrough
+- Application: Evaluate when tipping points occur
+
+### 3. Biology Models
+
+#### Evolution
+- Survival of the fittest, continuous iteration
+- Small experiments, rapid adaptation
+- Application: Analyze adaptive strategies in content
+
+#### Ecosystem
+- Complex networks of interdependence
+- Balance and diversity
+- Application: Understand systemic issues
+
+#### Red Queen Effect
+- Must keep running to stay in same place
+- Continuous progress in competitive environments
+- Application: Evaluate competitive strategies
+
+### 4. Psychology Models
+
+#### Cognitive Biases
+- Confirmation bias, anchoring, availability heuristic
+- Systematic thinking errors
+- Application: Identify logical flaws in arguments
+
+#### Loss Aversion
+- Motivation to avoid losses > gain benefits
+- Asymmetric risk decision-making
+- Application: Understand decision motivations
+
+#### Social Proof
+- Herd mentality and group influence
+- Others' behavior affects judgment
+- Application: Analyze persuasive power of arguments
+
+### 5. Economics Models
+
+#### Supply and Demand
+- Price determined by market equilibrium
+- Scarcity creates value
+- Application: Analyze market-related articles
+
+#### Marginal Utility
+- Value of additional units decreases
+- Optimal point isn't maximum
+- Application: Evaluate resource allocation recommendations
+
+#### Incentives
+- "Show me the incentive and I'll show you the outcome"
+- People respond to incentives
+- Application: Understand motivations behind behaviors
+
+### 6. Mathematics/Statistics Models
+
+#### Normal Distribution
+- Most cases cluster around average
+- Extreme cases are rare
+- Application: Evaluate probabilities and risks
+
+#### Power Law
+- 80/20 rule (Pareto Principle)
+- Few factors produce most results
+- Application: Identify key factors
+
+#### Regression to the Mean
+- Extreme results tend toward average
+- Avoid overreaction to outliers
+- Application: Evaluate representativeness of exceptional cases
+
+### 7. Systems Thinking Models
+
+#### Feedback Loops
+- Positive feedback: amplifying effects
+- Negative feedback: balancing stability
+- Application: Identify causal relationships
+
+#### Emergence
+- Whole is greater than sum of parts
+- System-level properties
+- Application: Understand complex systems
+
+#### Bottleneck
+- Critical constraint limiting system performance
+- Optimizing bottleneck yields maximum benefit
+- Application: Find core problems
+
+## Application Method
+
+### Step 1: Identify Problem Type
+
+```markdown
+Problem Classification:
+- [ ] Decision problem → Use: Opportunity cost, Loss aversion, Incentives
+- [ ] System problem → Use: Feedback loops, Emergence, Ecosystem
+- [ ] Growth problem → Use: Compounding, Leverage, Power law
+- [ ] Competition problem → Use: Evolution, Red Queen effect, Game theory
+```
+
+### Step 2: Apply Multiple Models
+
+**Rule**: Use at least 3 models from different disciplines
+
+```markdown
+## Multi-Perspective Analysis
+
+### Physics Perspective (Leverage)
+- Observation: Key actions proposed in article
+- Analysis: Which action yields maximum output with minimum input?
+- Conclusion: [Identify leverage points]
+
+### Psychology Perspective (Cognitive Biases)
+- Observation: Argumentation approach
+- Analysis: Any confirmation or survivorship bias present?
+- Conclusion: [Evaluate argument quality]
+
+### Economics Perspective (Incentives)
+- Observation: Stakeholders involved
+- Analysis: Are incentives aligned?
+- Conclusion: [Understand behavioral motivations]
+```
+
+### Step 3: Find Model Intersections
+
+```markdown
+## Cross-Model Insights
+
+When multiple models point to same conclusion → confidence ↑
+When models contradict → need deeper investigation
+
+Intersection discoveries:
+1. [Model A] + [Model B] → [Shared insight]
+2. [Contradiction] → [Issue requiring further analysis]
+```
+
+### Step 4: Synthesize Judgment
+
+```markdown
+## Integrated Conclusion
+
+Based on multi-model analysis:
+- ✅ Strongly supported views: [List]
+- ⚠️  Proceed with caution: [List]
+- ❌ Problematic assumptions: [List]
+
+Meta-cognitive check:
+- Did I use sufficiently diverse models?
+- Any important perspectives missing?
+- Over-reliance on any single model?
+```
+
+## Practical Example
+
+### Example: Analyzing Startup Article
+
+**Article Claim**: "Rapid growth is key to startup success"
+
+#### Multi-Model Analysis:
+
+**1. Ecosystem Model (Biology)**
+- Insight: Too-rapid growth can disrupt organizational "ecosystem balance"
+- Risk: Culture dilution, quality decline
+
+**2. Critical Mass Model (Physics)**
+- Insight: Must reach certain scale to survive
+- Support: Network effects require user base
+
+**3. Marginal Utility Model (Economics)**
+- Insight: Growth benefits diminish
+- Question: Is unlimited growth speed pursuit rational?
+
+**4. Feedback Loop Model (Systems)**
+- Insight: Rapid growth → resource strain → quality drop → user churn (negative feedback)
+- Risk: Growth trap
+
+**Synthesized Judgment**:
+- ✅ Article valid: Early stage needs rapid market validation
+- ⚠️  Missing: Sustainable vs. growth-at-all-costs
+- ❌ Overlooked: Industry/stage-specific growth rhythms
+
+## Common Pitfalls
+
+### ❌ Wrong Usage
+
+1. **Model Misuse**: Force-fitting irrelevant models
+2. **Single Dependency**: Actually using only one model, pretending it's multiple
+3. **Over-complexity**: Piling models without real insights
+4. **Ignoring Context**: Not considering specific situational differences
+
+### ✅ Correct Usage
+
+1. **Choose Relevance**: Select models related to problem essence
+2. **Apply Deeply**: Truly understand model applicability
+3. **Seek Conflicts**: Pay special attention to model contradictions
+4. **Stay Flexible**: Adjust model selection based on new information
+
+## Building Your Model Library
+
+### Beginner Level (Essential)
+- First principles
+- Opportunity cost
+- Compounding
+- Feedback loops
+- Cognitive biases
+
+### Intermediate Level (Expansion)
+- Ecosystem
+- Power law
+- Emergence
+- Red Queen effect
+- Game theory
+
+### Advanced Level (Specialization)
+- Deepen based on your domain
+- Cross-disciplinary integration
+- Create your own model combinations
+
+## Learning Recommendations
+
+1. **Broad Reading**: Study classics from different disciplines
+2. **Deliberate Practice**: Try applying 3+ models to every problem
+3. **Build Index**: Maintain personal "model → use case" catalog
+4. **Reflect**: Note which model combinations work especially well
+5. **Teach Others**: Explaining models deepens understanding
+
+## Recommended Resources
+
+**Books**:
+- "Poor Charlie's Almanack" - Charlie Munger
+- "The Art of Thinking Clearly" - Rolf Dobelli
+- "Principles" - Ray Dalio
+- "Super Thinking" - Gabriel Weinberg
+
+**Key Quote**:
+> "You must know the big ideas in the big disciplines and use them routinely—all of them, not just a few."
+> — Charlie Munger
+
+## Integration with Other Frameworks
+
+- **Critical Thinking**: Mental models help identify argument blind spots
+- **Systems Thinking**: Provides more tools for analyzing systems
+- **First Principles**: Can serve as one of the mental models
+- **Six Thinking Hats**: Complementary multi-perspective method
+
+---
+
+**Remember**: The goal of mental models isn't using more models, but gaining deeper insights. Quality > Quantity.
+
+---
+
+## ADOPT citation
+
+Adapted from an external reference.