@monoes/monomindcli 2.15.2 → 2.15.4

package/org-skills/debugging-wizard/references/systematic-debugging.md

@@ -0,0 +1,367 @@
+# Systematic Debugging
+
+---
+
+## Core Principle
+
+> **NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.**
+
+Jumping to fixes without understanding causes creates more bugs. Systematic debugging prevents the "fix one thing, break two more" cycle.
+
+---
+
+## The Four Mandatory Phases
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    SYSTEMATIC DEBUGGING                      │
+├─────────────────────────────────────────────────────────────┤
+│  Phase 1: ROOT CAUSE INVESTIGATION                          │
+│  ├── Read error messages thoroughly                         │
+│  ├── Reproduce reliably with documented steps               │
+│  ├── Examine recent changes                                 │
+│  └── Trace data flow backward                               │
+├─────────────────────────────────────────────────────────────┤
+│  Phase 2: PATTERN ANALYSIS                                   │
+│  ├── Find similar working implementations                   │
+│  ├── Study reference implementations completely             │
+│  └── Document all differences                               │
+├─────────────────────────────────────────────────────────────┤
+│  Phase 3: HYPOTHESIS TESTING                                 │
+│  ├── Form specific, written hypothesis                      │
+│  ├── Test with minimal, isolated changes                    │
+│  └── One variable at a time                                 │
+├─────────────────────────────────────────────────────────────┤
+│  Phase 4: IMPLEMENTATION                                     │
+│  ├── Create failing test case                               │
+│  ├── Implement single fix addressing root cause             │
+│  └── Verify no new breakage                                 │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Phase 1: Root Cause Investigation
+
+**Objective:** Understand exactly what is failing and why before attempting any fix.
+
+### Step 1.1: Read Error Messages Thoroughly
+
+```bash
+# Don't just read the first line
+TypeError: Cannot read property 'map' of undefined
+    at UserList.render (UserList.tsx:24)
+    at renderWithHooks (react-dom.js:14985)
+    at mountIndeterminateComponent (react-dom.js:17811)
+```
+
+**Key questions:**
+- What exact operation failed?
+- Where in the code (file, line)?
+- What was the call stack?
+- Are there multiple errors or just one?
+
+### Step 1.2: Reproduce Reliably
+
+```markdown
+## Reproduction Steps
+1. Navigate to /users
+2. Click "Load More" button
+3. Wait for loading spinner
+4. **ERROR: "Cannot read property 'map' of undefined"**
+
+## Environment
+- Browser: Chrome 120
+- User: Admin role
+- Data state: 50+ users in database
+```
+
+**Requirement:** Document exact steps that reproduce the bug 100% of the time.
+
+### Step 1.3: Examine Recent Changes
+
+```bash
+# What changed recently?
+git log --oneline -10
+
+# What specifically changed in the failing file?
+git log -p UserList.tsx
+
+# When did this start failing?
+git bisect start
+git bisect bad HEAD
+git bisect good v1.2.0
+```
+
+### Step 1.4: Trace Data Flow Backward
+
+```typescript
+// Error happens here:
+users.map(u => u.name)  // users is undefined
+
+// Trace backward:
+// Where does 'users' come from?
+const users = props.users;
+
+// Where do props come from?
+<UserList users={data.users} />
+
+// Where does data come from?
+const { data } = useQuery(GET_USERS);
+
+// ROOT CAUSE: Query returns { users: null } when loading
+```
+
+### Step 1.5: Add Diagnostic Instrumentation
+
+```typescript
+// Add temporary logging at boundaries
+console.log('[UserList] props:', JSON.stringify(props));
+console.log('[UserList] users type:', typeof props.users);
+console.log('[UserList] users value:', props.users);
+
+// Check at data source
+console.log('[API] Response:', response);
+console.log('[API] Response.data:', response.data);
+```
+
+---
+
+## Phase 2: Pattern Analysis
+
+**Objective:** Find working examples to understand what correct behavior looks like.
+
+### Step 2.1: Locate Similar Working Implementations
+
+```bash
+# Find similar components that work correctly
+grep -r "useQuery" src/components/ --include="*.tsx"
+
+# Find how other lists handle loading states
+grep -r "loading" src/components/*List* --include="*.tsx"
+```
+
+### Step 2.2: Study Reference Implementations Completely
+
+```typescript
+// WORKING: ProductList.tsx
+function ProductList({ products, loading }) {
+  if (loading) return <Spinner />;
+  if (!products) return null;  // ← Handles undefined case
+
+  return products.map(p => <ProductItem key={p.id} {...p} />);
+}
+
+// BROKEN: UserList.tsx
+function UserList({ users, loading }) {
+  if (loading) return <Spinner />;
+  // Missing: !users check
+
+  return users.map(u => <UserItem key={u.id} {...u} />);  // 💥 Crashes
+}
+```
+
+### Step 2.3: Document All Differences
+
+| Aspect | Working (ProductList) | Broken (UserList) |
+|--------|----------------------|-------------------|
+| Null check | `if (!products)` | Missing |
+| Default value | `products ?? []` | None |
+| Loading handled | Before render | Before render |
+| Error handled | Returns ErrorState | Missing |
+
+---
+
+## Phase 3: Hypothesis Testing
+
+**Objective:** Verify your understanding with controlled experiments.
+
+### Step 3.1: Form Specific, Written Hypothesis
+
+```markdown
+## Hypothesis #1
+**Statement:** The crash occurs because `users` is undefined when the
+query is complete but returns no data.
+
+**Prediction:** Adding a null check before `.map()` will prevent the crash.
+
+**Test:** Add `if (!users) return null;` before the map call.
+```
+
+### Step 3.2: Test with Minimal Changes
+
+```typescript
+// Change ONLY one thing
+function UserList({ users, loading }) {
+  if (loading) return <Spinner />;
+  if (!users) return null;  // ← Single change
+
+  return users.map(u => <UserItem key={u.id} {...u} />);
+}
+```
+
+### Step 3.3: One Variable at a Time
+
+```markdown
+## Test Results
+
+| Hypothesis | Change | Result | Conclusion |
+|------------|--------|--------|------------|
+| #1: Null check | Add `if (!users)` | ✓ Pass | Confirmed |
+
+Do NOT test multiple hypotheses simultaneously.
+```
+
+---
+
+## Phase 4: Implementation
+
+**Objective:** Fix the bug permanently with proper safeguards.
+
+### Step 4.1: Create Failing Test Case First
+
+```typescript
+describe('UserList', () => {
+  it('should handle undefined users gracefully', () => {
+    // This test should FAIL before the fix
+    const { container } = render(<UserList users={undefined} loading={false} />);
+    expect(container).not.toThrow();
+    expect(screen.queryByRole('list')).not.toBeInTheDocument();
+  });
+});
+```
+
+### Step 4.2: Implement Single Fix
+
+```typescript
+function UserList({ users, loading }: UserListProps) {
+  if (loading) return <Spinner />;
+  if (!users || users.length === 0) {
+    return <EmptyState message="No users found" />;
+  }
+
+  return (
+    <ul role="list">
+      {users.map(u => <UserItem key={u.id} {...u} />)}
+    </ul>
+  );
+}
+```
+
+### Step 4.3: Verify No New Breakage
+
+```bash
+# Run full test suite
+npm test
+
+# Run specific component tests
+npm test UserList
+
+# Run integration tests
+npm run test:integration
+
+# Verify in browser
+# 1. Normal case: 50 users
+# 2. Empty case: 0 users
+# 3. Loading case: spinner shows
+# 4. Error case: error message shows
+```
+
+---
+
+## The Three-Fix Threshold
+
+> **After 3 failed fix attempts → STOP.**
+
+Three failures in different locations signals architectural problems, not isolated bugs.
+
+### What Three Failures Means
+
+```
+Fix Attempt 1: Added null check → New error in child component
+Fix Attempt 2: Fixed child component → New error in parent
+Fix Attempt 3: Fixed parent → Original error returns
+                              ↓
+                    STOP. QUESTION ARCHITECTURE.
+```
+
+### At the Threshold, Do This
+
+1. **Stop fixing symptoms**
+2. **Document the pattern** of failures
+3. **Identify architectural assumptions** being violated
+4. **Propose structural change** rather than patch
+5. **Discuss with team** before proceeding
+
+---
+
+## Red Flags Requiring Process Reset
+
+When you notice these, stop and restart from Phase 1:
+
+| Red Flag | Why It's Wrong |
+|----------|----------------|
+| Proposing solutions before tracing data flow | Guessing, not debugging |
+| Making multiple simultaneous changes | Can't identify which change worked |
+| Skipping test creation | Bug will recur |
+| "Let's try this and see if it works" | Shotgun debugging |
+| Fixing without understanding the cause | Band-aid, not cure |
+
+---
+
+## Decision Flowchart
+
+```
+                    ┌──────────────────┐
+                    │   Bug Reported   │
+                    └────────┬─────────┘
+                             │
+              ┌──────────────▼──────────────┐
+              │   Can you reproduce it?      │
+              └──────────────┬──────────────┘
+                    No       │       Yes
+            ┌────────────────┴────────────────┐
+            ▼                                  ▼
+    ┌───────────────┐               ┌─────────────────┐
+    │ Get more info │               │ Trace data flow │
+    └───────────────┘               └────────┬────────┘
+                                             │
+                              ┌──────────────▼──────────────┐
+                              │ Do you understand the cause? │
+                              └──────────────┬──────────────┘
+                                    No       │       Yes
+                    ┌────────────────────────┴─────────┐
+                    ▼                                   ▼
+            ┌───────────────┐               ┌─────────────────┐
+            │ Study working │               │ Write hypothesis│
+            │   examples    │               └────────┬────────┘
+            └───────────────┘                        │
+                                             ┌───────▼───────┐
+                                             │  Write test   │
+                                             └───────┬───────┘
+                                                     │
+                                             ┌───────▼───────┐
+                                             │  Implement    │
+                                             └───────┬───────┘
+                                                     │
+                                  ┌──────────────────▼──────────────────┐
+                                  │          Does test pass?            │
+                                  └──────────────────┬──────────────────┘
+                                            No       │       Yes
+                            ┌────────────────────────┴──────────┐
+                            ▼                                    ▼
+                    ┌───────────────┐                  ┌─────────────────┐
+                    │ Attempt < 3?  │                  │      Done       │
+                    └───────┬───────┘                  └─────────────────┘
+                    No      │      Yes
+            ┌───────────────┴─────────────────┐
+            ▼                                  ▼
+    ┌───────────────────┐          ┌─────────────────────┐
+    │ Question          │          │ Return to Phase 1   │
+    │ architecture      │          └─────────────────────┘
+    └───────────────────┘
+```
+
+---
+
+*Content adapted from [obra/superpowers](https://github.com/obra/superpowers) by Jesse Vincent (@obra), MIT License.*

package/org-skills/deep-research/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alireza Rezvani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/org-skills/deep-research/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: deep-research
+description: "Run a disciplined, multi-source research investigation for a high-stakes question or decision — fan-out web search across many channels, parallel sub-agents, source triangulation (each claim backed by ≥3 independent sources), an adversarial review pass, and every source saved to its own file with verbatim quotes for reuse."
+tags: ["research"]
+tools: []
+license: MIT
+source: https://github.com/alirezarezvani/claude-skills
+source_path: "research/deep-research/skills/deep-research"
+source_commit: 19392f7a08264ed00486a251f5b2098321771f94
+---
+# Deep Research — Disciplined Meta-Research
+
+Turn "research this topic" into an auditable, reusable investigation instead of a one-shot wall of text. The output is a folder you can return to in a month: every claim traces to a specific source file, the plan documents *why* each choice was made, and a refresh protocol lets you update it later without re-running everything.
+
+**This is the heavy, methodical end of research.** It is not a fast overview — it is the workflow you reach for when getting the answer *wrong* costs more than the tokens spent getting it right.
+
+## How it differs from a quick research router
+
+A router-style research skill (keyword-classify → delegate → short sequential search → markdown brief) is optimal when you need an answer fast and the decision risk is low. `deep-research` is the opposite trade: it pays for rigor. Use it when the answer feeds a strategy, an irreversible decision, a published artifact, or a hypothesis you need to actually test — situations where a shallow fallback would be a liability.
+
+Concretely, `deep-research` adds what a fast overview does not: falsifiable hypotheses up front, parallel sub-agent fan-out across many channels, triangulation with explicit source-type diversity, a mandatory adversarial pass, per-source files with verbatim quotes, and a `refresh_targets.md` for delta-updates later.
+
+## The pipeline (9 phases)
+
+Depth scales with the task — `shallow` runs the core phases inline; `medium`/`deep` add capability discovery, verification, and refresh targets.
+
+| # | Phase | What it does |
+|---|-------|--------------|
+| 1 | **Reframe** | Rewrite the question, fix the underlying decision, state 2–4 *falsifiable* hypotheses |
+| 2 | **Genre & blocks** | Pick the report genre (qa / explainer / decision / landscape / validation / custom) and its building blocks |
+| 3 | **Plan** | Write `plan.md`: scope, structure, sourcing strategy, opposition queries, risk register, stop-criteria |
+| 3.5 | **Capability discovery** | Audit available API keys/channels in the environment; map subtopics to sources; fall back to HTML where needed |
+| 4 | **Search** (loop) | Dispatch sources → launch sub-agents in parallel → fetch & dedup → save each to `sources/NN.md`; re-evaluate between rounds |
+| 5 | **Score & triangulate** | Rate every source on Credibility / Recency / Bias; require ≥3 independent, differently-typed sources per thesis |
+| 6 | **Synthesize + adversarial** | Assemble the report from blocks, run 4 self-critique questions, add steel-manned counter-arguments |
+| 6.5 | **Verify** | Lightweight citation check before closing |
+| 7 | **Refresh targets** | Extract entities / numbers / hypotheses into `refresh_targets.md` — the entry point for future updates |
+
+## Core mechanisms
+
+These are what separate a documented investigation from a confident guess:
+
+- **Triangulation.** Every thesis must be backed by ≥3 independent sources of *different types* (primary / academic / industry / discussion). A claim with fewer is flagged "insufficient evidence," not stated as fact.
+- **Source-grounding.** Each source becomes its own `sources/NN_slug.md` with metadata, verbatim quotes, and scores. No dangling claim — every assertion links back to a specific file. An empty fetch produces an empty claim, never a fabricated citation.
+- **Adversarial pass.** Phase 6 always runs the strongest available reasoning: 4 self-critique questions plus an active search for counter-arguments and disconfirming evidence.
+- **Falsifiable hypotheses.** Phase 1 commits to 2–4 hypotheses; Phases 5–6 explicitly confirm or refute each against the evidence, or mark it under-determined.
+- **Parallel sub-agents.** Phase 4 launches search sub-agents concurrently (cheap models for broad web sweeps, stronger ones for reasoning-heavy subtopics) — never one-at-a-time.
+- **Refresh protocol.** Phase 7 emits `refresh_targets.md`; an `update <slug>` run produces a delta (new entrants, entity changes, refreshed numbers, adversarial triggers) instead of replaying the whole investigation.
+- **Atomic findings.** Reusable theses in `findings/FN.md` plus a `sources.csv` index — research compounds across questions instead of starting from zero each time.
+
+## Output structure
+
+```
+<root>/<slug>/
+├── plan.md                  # scope, sourcing strategy, risk register, changelog
+├── sources.csv              # index of every source with scores
+├── sources/
+│   ├── 01_<slug>.md         # one file = one source (metadata + verbatim quotes)
+│   └── ...
+├── findings/                # atomic, reusable theses (larger investigations)
+│   └── F1_<short>.md
+├── refresh_targets.md       # what to watch on update (medium/deep)
+├── diffs/
+│   └── YYYY-MM-DD_delta.md   # delta from an `update <slug>` run
+└── YYYY-MM-DD_<genre>.md     # final report
+```
+
+## When to use
+
+- A low-quality answer is expensive: strategy, business plan, report, or article groundwork.
+- Comparing N institutions, products, methodologies, or markets and you need defensible reasoning.
+- Validating a hypothesis or a decision against external data.
+- Meta-research: "understand how X works," "map the landscape of Y," answering a connected series of questions.
+
+## Anti-Patterns
+
+- **Don't skip the existing-work check.** Before searching, see whether the answer is already in the project or in a prior research folder — you risk re-researching something you already have.
+- **Don't skip reframing**, even when the request "seems clear." The decision behind the question usually changes the search.
+- **Don't output to chat only.** Always persist sources and the report to files — the reuse value is in the folder, not the transcript.
+- **Don't fabricate citations.** If a fetch returns nothing, the claim is empty — never invent a plausible URL. Bind every claim to a saved verbatim quote.
+- **Don't build conclusions on a thin corpus.** Too few sources, or sources that all share one type, means triangulation hasn't happened — say so rather than overstating confidence.
+- **Don't skip the adversarial pass** on medium/deep investigations. Confirmation-only research is the failure mode this skill exists to prevent.
+- **Don't run sub-agents sequentially.** Fan-out in parallel; serial search wastes the wall-clock advantage.
+- **Don't collapse `sources/` into one file.** Per-source files are what make findings searchable and reusable across investigations.
+- **Don't pick the heaviest model for everything.** Match model to subtask — cheap for broad sweeps, strong for synthesis and the adversarial pass.
+
+## Cross-References
+
+- **research router** — for fast topic overviews where decision risk is low; `deep-research` is the heavyweight alternative when rigor matters more than speed.
+- **competitive-teardown** — for comparing N competitors on a structured 12-dimension matrix.
+- **litreview / dossier / patent** — domain specialists when the investigation is narrowly academic, person/company-focused, or patent-focused.

package/org-skills/deep-research/references/full-catalog.md

@@ -0,0 +1,15 @@
+# Full catalog & upstream
+
+This skill is a self-contained methodology. The complete, continuously-maintained catalog it draws on — **29 search channels, 460+ statistical sources, 39 validated APIs, and 103 report blocks** — lives in the upstream project, where a weekly CI job re-validates every API endpoint and flags dead links:
+
+**https://github.com/Socialpranker/claude-deep-research**
+
+What's upstream (kept there to avoid duplicating a large, fast-moving catalog):
+
+- `phases.yaml` — the canonical phase definitions and depth gating.
+- `references/channels.md` — the 29 named search channels.
+- `references/stat_sources/` — the 460+ statistical-source registry.
+- `references/api_sources/` — the 39 API definitions with auth and fallback notes.
+- `references/blocks/` — the 103 report building blocks per genre.
+
+The `SKILL.md` here is the operating discipline; pull the upstream catalog when you want the full sourcing surface or the auto-validated API list.

package/{dist/src/orgrt/role-skills/defender.md → org-skills/defender/SKILL.md}

@@ -1,3 +1,11 @@
+---
+name: defender
+description: "Defender role best practices. Provides zealous advocacy for the opposing party within ethical bounds — the defender's job is to test the prosecution's case rigorously and ensure every weakness, gap, and alternative explanation is surfaced, not to assume the accusation is true."
+tags: ["legal"]
+tools: []
+license: Apache-2.0
+source: https://github.com/monoes/monomind
+---
 # Defender — Best Practices
 
 ## Focus

package/org-skills/dependency-upgrade/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Seth Hobson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.