mindsystem-cc 3.0.0

package/mindsystem/references/research-pitfalls.md

@@ -0,0 +1,233 @@
+# Research Pitfalls Reference
+
+## DEPRECATED
+
+**This reference has been consolidated into the ms-researcher agent.**
+
+The verification protocols and pitfall patterns now live in:
+- `agents/ms-researcher.md` (section: `<verification_protocol>`)
+
+The content below is preserved for reference but is no longer the primary source.
+
+---
+
+*Deprecated: 2026-01-15*
+*Replaced by: agents/ms-researcher.md*
+
+---
+
+<research_pitfalls>
+
+<purpose>
+This document catalogs research mistakes discovered in production use, providing specific patterns to avoid and verification strategies to prevent recurrence.
+</purpose>
+
+<known_pitfalls>
+
+<pitfall_config_scope>
+**What**: Assuming global configuration means no project-scoping exists
+**Example**: Concluding "MCP servers are configured GLOBALLY only" while missing project-scoped `.mcp.json`
+**Why it happens**: Not explicitly checking all known configuration patterns
+**Prevention**:
+```xml
+<verification_checklist>
+**CRITICAL**: Verify ALL configuration scopes:
+- User/global scope - System-wide configuration
+- Project scope - Project-level configuration files
+- Local scope - Project-specific user overrides
+- Workspace scope - IDE/tool workspace settings
+- Environment scope - Environment variables
+</verification_checklist>
+```
+</pitfall_config_scope>
+
+<pitfall_search_vagueness>
+**What**: Asking researchers to "search for documentation" without specifying where
+**Example**: "Research MCP documentation" -> finds outdated community blog instead of official docs
+**Why it happens**: Vague research instructions don't specify exact sources
+**Prevention**:
+```xml
+<sources>
+Official sources (use WebFetch):
+- https://exact-url-to-official-docs
+- https://exact-url-to-api-reference
+
+Search queries (use WebSearch):
+- "specific search query {current_year}"
+- "another specific query {current_year}"
+</sources>
+```
+</pitfall_search_vagueness>
+
+<pitfall_deprecated_features>
+**What**: Finding archived/old documentation and concluding feature doesn't exist
+**Example**: Finding 2022 docs saying "feature not supported" when current version added it
+**Why it happens**: Not checking multiple sources or recent updates
+**Prevention**:
+```xml
+<verification_checklist>
+- Check current official documentation
+- Review changelog/release notes for recent updates
+- Verify version numbers and publication dates
+- Cross-reference multiple authoritative sources
+</verification_checklist>
+```
+</pitfall_deprecated_features>
+
+<pitfall_tool_variations>
+**What**: Conflating capabilities across different tools/environments
+**Example**: "Claude Desktop supports X" does not mean "Claude Code supports X"
+**Why it happens**: Not explicitly checking each environment separately
+**Prevention**:
+```xml
+<verification_checklist>
+- Claude Desktop capabilities
+- Claude Code capabilities
+- VS Code extension capabilities
+- API/SDK capabilities
+Document which environment supports which features
+</verification_checklist>
+```
+</pitfall_tool_variations>
+
+<pitfall_negative_claims>
+**What**: Making definitive "X is not possible" statements without official source verification
+**Example**: "Folder-scoped MCP configuration is not supported" (missing `.mcp.json`)
+**Why it happens**: Drawing conclusions from absence of evidence rather than evidence of absence
+**Prevention**:
+```xml
+<critical_claims_audit>
+For any "X is not possible" or "Y is the only way" statement:
+- [ ] Is this verified by official documentation stating it explicitly?
+- [ ] Have I checked for recent updates that might change this?
+- [ ] Have I verified all possible approaches/mechanisms?
+- [ ] Am I confusing "I didn't find it" with "it doesn't exist"?
+</critical_claims_audit>
+```
+</pitfall_negative_claims>
+
+<pitfall_missing_enumeration>
+**What**: Investigating open-ended scope without enumerating known possibilities first
+**Example**: "Research configuration options" instead of listing specific options to verify
+**Why it happens**: Not creating explicit checklist of items to investigate
+**Prevention**:
+```xml
+<verification_checklist>
+Enumerate ALL known options FIRST:
+- Option 1: [specific item]
+- Option 2: [specific item]
+- Option 3: [specific item]
+- Check for additional unlisted options
+
+For each option above, document:
+- Existence (confirmed/not found/unclear)
+- Official source URL
+- Current status (active/deprecated/beta)
+</verification_checklist>
+```
+</pitfall_missing_enumeration>
+
+<pitfall_single_source>
+**What**: Relying on a single source for critical claims
+**Example**: Using only Stack Overflow answer from 2021 for current best practices
+**Why it happens**: Not cross-referencing multiple authoritative sources
+**Prevention**:
+```xml
+<source_verification>
+For critical claims, require multiple sources:
+- [ ] Official documentation (primary)
+- [ ] Release notes/changelog (for currency)
+- [ ] Additional authoritative source (for verification)
+- [ ] Contradiction check (ensure sources agree)
+</source_verification>
+```
+</pitfall_single_source>
+
+<pitfall_assumed_completeness>
+**What**: Assuming search results are complete and authoritative
+**Example**: First Google result is outdated but assumed current
+**Why it happens**: Not verifying publication dates and source authority
+**Prevention**:
+```xml
+<source_verification>
+For each source consulted:
+- [ ] Publication/update date verified (prefer recent/current)
+- [ ] Source authority confirmed (official docs, not blogs)
+- [ ] Version relevance checked (matches current version)
+- [ ] Multiple search queries tried (not just one)
+</source_verification>
+```
+</pitfall_assumed_completeness>
+</known_pitfalls>
+
+<red_flags>
+
+<red_flag_zero_not_found>
+**Warning**: Every investigation succeeds perfectly
+**Problem**: Real research encounters dead ends, ambiguity, and unknowns
+**Action**: Expect honest reporting of limitations, contradictions, and gaps
+</red_flag_zero_not_found>
+
+<red_flag_no_confidence>
+**Warning**: All findings presented as equally certain
+**Problem**: Can't distinguish verified facts from educated guesses
+**Action**: Require confidence levels (High/Medium/Low) for key findings
+</red_flag_no_confidence>
+
+<red_flag_missing_urls>
+**Warning**: "According to documentation..." without specific URL
+**Problem**: Can't verify claims or check for updates
+**Action**: Require actual URLs for all official documentation claims
+</red_flag_missing_urls>
+
+<red_flag_no_evidence>
+**Warning**: "X cannot do Y" or "Z is the only way" without citation
+**Problem**: Strong claims require strong evidence
+**Action**: Flag for verification against official sources
+</red_flag_no_evidence>
+
+<red_flag_incomplete_enum>
+**Warning**: Verification checklist lists 4 items, output covers 2
+**Problem**: Systematic gaps in coverage
+**Action**: Ensure all enumerated items addressed or marked "not found"
+</red_flag_incomplete_enum>
+</red_flags>
+
+<continuous_improvement>
+
+When research gaps occur:
+
+1. **Document the gap**
+   - What was missed or incorrect?
+   - What was the actual correct information?
+   - What was the impact?
+
+2. **Root cause analysis**
+   - Why wasn't it caught?
+   - Which verification step would have prevented it?
+   - What pattern does this reveal?
+
+3. **Update this document**
+   - Add new pitfall entry
+   - Update relevant checklists
+   - Share lesson learned
+</continuous_improvement>
+
+<quick_reference>
+
+Before submitting research, verify:
+
+- [ ] All enumerated items investigated (not just some)
+- [ ] Negative claims verified with official docs
+- [ ] Multiple sources cross-referenced for critical claims
+- [ ] URLs provided for all official documentation
+- [ ] Publication dates checked (prefer recent/current)
+- [ ] Tool/environment-specific variations documented
+- [ ] Confidence levels assigned honestly
+- [ ] Assumptions distinguished from verified facts
+- [ ] "What might I have missed?" review completed
+
+**Living Document**: Update after each significant research gap
+**Lessons From**: MCP configuration research gap (missed `.mcp.json`)
+</quick_reference>
+</research_pitfalls>

package/mindsystem/references/scope-estimation.md

@@ -0,0 +1,256 @@
+<scope_estimation>
+Plans must maintain consistent quality from first task to last. This requires understanding quality degradation and splitting aggressively.
+
+<quality_insight>
+Claude degrades when it *perceives* context pressure and enters "completion mode."
+
+| Context Usage | Quality | Claude's State |
+|---------------|---------|----------------|
+| 0-30% | PEAK | Thorough, comprehensive |
+| 30-50% | GOOD | Confident, solid work |
+| 50-70% | DEGRADING | Efficiency mode begins |
+| 70%+ | POOR | Rushed, minimal |
+
+**The 40-50% inflection point:** Claude sees context mounting and thinks "I'd better conserve now." Result: "I'll complete the remaining tasks more concisely" = quality crash.
+
+**The rule:** Stop BEFORE quality degrades, not at context limit.
+</quality_insight>
+
+<context_target>
+**Plans should complete within ~50% of context usage.**
+
+Why 50% not 80%?
+- No context anxiety possible
+- Quality maintained start to finish
+- Room for unexpected complexity
+- If you target 80%, you've already spent 40% in degradation mode
+</context_target>
+
+<task_rule>
+**Each plan: 2-3 tasks maximum. Stay under 50% context.**
+
+| Task Complexity | Tasks/Plan | Context/Task | Total |
+|-----------------|------------|--------------|-------|
+| Simple (CRUD, config) | 3 | ~10-15% | ~30-45% |
+| Complex (auth, payments) | 2 | ~20-30% | ~40-50% |
+| Very complex (migrations, refactors) | 1-2 | ~30-40% | ~30-50% |
+
+**When in doubt: Default to 2 tasks.** Better to have an extra plan than degraded quality.
+</task_rule>
+
+<tdd_plans>
+**TDD features get their own plans. Target ~40% context.**
+
+TDD requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. This is fundamentally heavier than linear task execution.
+
+| TDD Feature Complexity | Context Usage |
+|------------------------|---------------|
+| Simple utility function | ~25-30% |
+| Business logic with edge cases | ~35-40% |
+| Complex algorithm | ~40-50% |
+
+**One feature per TDD plan.** If features are trivial enough to batch, they're trivial enough to skip TDD.
+
+**Why TDD plans are separate:**
+- TDD consumes 40-50% context for a single feature
+- Dedicated plans ensure full quality throughout RED-GREEN-REFACTOR
+- Each TDD feature gets fresh context, peak quality
+
+See `~/.claude/mindsystem/references/tdd.md` for TDD plan structure.
+</tdd_plans>
+
+<split_signals>
+
+<always_split>
+- **More than 3 tasks** - Even if tasks seem small
+- **Multiple subsystems** - DB + API + UI = separate plans
+- **Any task with >5 file modifications** - Split by file groups
+- **Checkpoint + implementation work** - Checkpoints in one plan, implementation after in separate plan
+- **Discovery + implementation** - DISCOVERY.md in one plan, implementation in another
+</always_split>
+
+<consider_splitting>
+- Estimated >5 files modified total
+- Complex domains (auth, payments, data modeling)
+- Any uncertainty about approach
+- Natural semantic boundaries (Setup -> Core -> Features)
+</consider_splitting>
+</split_signals>
+
+<splitting_strategies>
+**Vertical slices (default):** Group by feature, not by layer.
+
+```
+PREFER: Plan 01 = User (model + API + UI)
+        Plan 02 = Product (model + API + UI)
+        Plan 03 = Order (model + API + UI)
+
+AVOID:  Plan 01 = All models
+        Plan 02 = All APIs (depends on 01)
+        Plan 03 = All UIs (depends on 02)
+```
+
+Vertical slices maximize parallelism: [01, 02, 03] run simultaneously.
+Horizontal layers force sequential execution: 01 → 02 → 03.
+
+**By dependency:** Only when genuine dependencies exist.
+```
+Plan 01: Auth foundation (middleware, JWT utils)
+Plan 02: Protected features (uses auth from 01)
+```
+
+**By complexity:** When one slice is much heavier.
+```
+Plan 01: Dashboard layout shell
+Plan 02: Data fetching and state
+Plan 03: Visualization components
+```
+</splitting_strategies>
+
+<dependency_awareness>
+**Plans declare dependencies explicitly via frontmatter.**
+
+```yaml
+# Independent plan (Wave 1 candidate)
+depends_on: []
+files_modified: [src/features/user/model.ts, src/features/user/api.ts]
+autonomous: true
+
+# Dependent plan (later wave)
+depends_on: ["03-01"]
+files_modified: [src/integration/stripe.ts]
+autonomous: true
+```
+
+**Wave assignment rules:**
+- `depends_on: []` + no file conflicts → Wave 1 (parallel)
+- `depends_on: ["XX"]` → runs after plan XX completes
+- Shared `files_modified` with sibling → sequential (by plan number)
+
+**SUMMARY references:**
+- Only reference prior SUMMARY if genuinely needed (imported types, decisions affecting this plan)
+- Independent plans need NO prior SUMMARY references
+- Reflexive chaining (02 refs 01, 03 refs 02) is an anti-pattern
+</dependency_awareness>
+
+<file_ownership>
+**Exclusive file ownership prevents conflicts:**
+
+```yaml
+# Plan 01 frontmatter
+files_modified: [src/models/user.ts, src/api/users.ts, src/components/UserList.tsx]
+
+# Plan 02 frontmatter
+files_modified: [src/models/product.ts, src/api/products.ts, src/components/ProductList.tsx]
+```
+
+No overlap → can run parallel.
+
+**If file appears in multiple plans:** Later plan depends on earlier (by plan number).
+**If file cannot be split:** Plans must be sequential for that file.
+</file_ownership>
+
+<anti_patterns>
+**Bad - Comprehensive plan:**
+```
+Plan: "Complete Authentication System"
+Tasks: 8 (models, migrations, API, JWT, middleware, hashing, login form, register form)
+Result: Task 1-3 good, Task 4-5 degrading, Task 6-8 rushed
+```
+
+**Good - Atomic plans:**
+```
+Plan 1: "Auth Database Models" (2 tasks)
+Plan 2: "Auth API Core" (3 tasks)
+Plan 3: "Auth API Protection" (2 tasks)
+Plan 4: "Auth UI Components" (2 tasks)
+Each: 30-40% context, peak quality, atomic commits
+```
+
+**Bad - Horizontal layers (sequential):**
+```
+Plan 01: Create User model, Product model, Order model
+Plan 02: Create /api/users, /api/products, /api/orders
+Plan 03: Create UserList UI, ProductList UI, OrderList UI
+```
+Result: 02 depends on 01, 03 depends on 02
+Waves: [01] → [02] → [03] (fully sequential)
+
+**Good - Vertical slices (parallel):**
+```
+Plan 01: User feature (model + API + UI)
+Plan 02: Product feature (model + API + UI)
+Plan 03: Order feature (model + API + UI)
+```
+Result: Each plan self-contained, no file overlap
+Waves: [01, 02, 03] (all parallel)
+</anti_patterns>
+
+<estimating_context>
+| Files Modified | Context Impact |
+|----------------|----------------|
+| 0-3 files | ~10-15% (small) |
+| 4-6 files | ~20-30% (medium) |
+| 7+ files | ~40%+ (large - split) |
+
+| Complexity | Context/Task |
+|------------|--------------|
+| Simple CRUD | ~15% |
+| Business logic | ~25% |
+| Complex algorithms | ~40% |
+| Domain modeling | ~35% |
+
+**2 tasks:** Simple ~30%, Medium ~50%, Complex ~80% (split)
+**3 tasks:** Simple ~45%, Medium ~75% (risky), Complex 120% (impossible)
+</estimating_context>
+
+<depth_calibration>
+**Depth controls compression tolerance, not artificial inflation.**
+
+| Depth | Typical Phases | Typical Plans/Phase | Tasks/Plan |
+|-------|----------------|---------------------|------------|
+| Quick | 3-5 | 1-3 | 2-3 |
+| Standard | 5-8 | 3-5 | 2-3 |
+| Comprehensive | 8-12 | 5-10 | 2-3 |
+
+Tasks/plan is CONSTANT at 2-3. The 50% context rule applies universally.
+
+**Key principle:** Derive from actual work. Depth determines how aggressively you combine things, not a target to hit.
+
+- Comprehensive auth = 8 plans (because auth genuinely has 8 concerns)
+- Comprehensive "add favicon" = 1 plan (because that's all it is)
+
+Don't pad small work to hit a number. Don't compress complex work to look efficient.
+
+**Comprehensive depth example:**
+Auth system at comprehensive depth = 8 plans (not 3 big ones):
+- 01: DB models (2 tasks)
+- 02: Password hashing (2 tasks)
+- 03: JWT generation (2 tasks)
+- 04: JWT validation middleware (2 tasks)
+- 05: Login endpoint (2 tasks)
+- 06: Register endpoint (2 tasks)
+- 07: Protected route patterns (2 tasks)
+- 08: Auth UI components (3 tasks)
+
+Each plan: fresh context, peak quality. More plans = more thoroughness, same quality per plan.
+</depth_calibration>
+
+<summary>
+**2-3 tasks, 50% context target:**
+- All tasks: Peak quality
+- Git: Atomic per-task commits
+- Parallel by default: Fresh context per subagent
+
+**The principle:** Aggressive atomicity. More plans, smaller scope, consistent quality.
+
+**The rules:**
+- If in doubt, split. Quality over consolidation.
+- Depth increases plan COUNT, never plan SIZE.
+- Vertical slices over horizontal layers.
+- Explicit dependencies via `depends_on` frontmatter.
+- Autonomous plans get parallel execution.
+
+**Commit rule:** Each plan produces 3-4 commits total (2-3 task commits + 1 docs commit).
+</summary>
+</scope_estimation>