icdev 0.0.3__py3-none-any.whl

goals/subagent_review.md

@@ -0,0 +1,205 @@
+# Goal: Two-Stage Subagent Review
+
+## Description
+
+When dispatching work to subagents, enforce a two-stage review after each task: first spec compliance (did it match requirements?), then code quality (is it well-built?). This catches both under-building and over-building.
+
+**Adapted from:** [obra/superpowers](https://github.com/obra/superpowers) subagent-driven-development skill.
+
+**The principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration.
+
+---
+
+## When to Use
+
+- Executing implementation plans via subagents
+- Any task dispatched with the Agent tool
+- Multi-step implementations where quality matters
+- Phase implementations (Forge Studio phases, feature rollouts)
+
+**When NOT to use:**
+- Simple research/exploration agents (Explore subagent type)
+- One-off file searches
+- Read-only operations
+
+---
+
+## Prerequisites
+
+- [ ] Implementation plan exists (from `goals/bite_sized_plans.md` or clear user directive)
+- [ ] Tasks are mostly independent (tightly coupled tasks should be sequential)
+
+---
+
+## Process
+
+### Step 1: Extract All Tasks Upfront
+
+Read the plan once. Extract all tasks with full text and context. Create a TodoWrite with all tasks. Do NOT make the subagent read the plan file — provide the full text directly.
+
+### Step 2: Per-Task Cycle
+
+For each task:
+
+```
+1. Dispatch IMPLEMENTER subagent
+   - Provide: full task text, context, relevant file paths
+   - Subagent: implements, tests, commits, self-reviews
+
+2. If implementer asks questions → answer, re-dispatch
+
+3. Dispatch SPEC REVIEWER subagent
+   - Provide: original task spec, list of changed files
+   - Reviewer checks:
+     ✓ All requirements from spec are implemented
+     ✓ Nothing extra was added (YAGNI)
+     ✓ Edge cases from spec are covered
+   - If issues found → implementer fixes → re-review
+
+4. Dispatch CODE QUALITY REVIEWER subagent
+   - Provide: changed files, project conventions
+   - Reviewer checks:
+     ✓ Code follows codebase patterns
+     ✓ No security vulnerabilities (OWASP top 10)
+     ✓ Tests are meaningful (not just coverage)
+     ✓ No magic numbers, clear naming
+     ✓ CUI markings present (if applicable)
+   - If issues found → implementer fixes → re-review
+
+5. Mark task complete in TodoWrite
+```
+
+**CRITICAL ORDER:** Spec compliance FIRST, then code quality. Never start quality review before spec is approved.
+
+### Step 3: Implementer Prompt Template
+
+When dispatching the implementer subagent:
+
+```markdown
+## Task: [Task name from plan]
+
+### Context
+[Where this fits in the larger feature. What was built before. What comes after.]
+
+### Requirements
+[Full task text from plan — copy-paste, don't summarize]
+
+### Files to Reference
+[List of existing files the implementer needs to read]
+
+### Constraints
+- Follow TDD: write failing test first, then implement
+- Use existing patterns from codebase (get_connection(), log_forge_event(), etc.)
+- Include CUI // SP-CTI marking on new files
+- Commit after completing the task
+
+### Expected Output
+- Summary of what was implemented
+- List of files created/modified
+- Test results (paste output)
+```
+
+### Step 4: Spec Reviewer Prompt Template
+
+```markdown
+## Spec Compliance Review
+
+### Original Specification
+[Full task text from plan]
+
+### Files Changed
+[List of files the implementer created/modified]
+
+### Review Checklist
+1. Are ALL requirements from the spec implemented?
+2. Is anything EXTRA added that wasn't requested? (YAGNI violation)
+3. Are edge cases from the spec covered?
+4. Do function signatures match what the spec described?
+5. Does the implementation match the architecture described?
+
+### Output Format
+- ✅ Spec compliant — all requirements met, nothing extra
+- ❌ Issues found:
+  - Missing: [what's not implemented]
+  - Extra: [what was added but not requested]
+  - Wrong: [what doesn't match spec]
+```
+
+### Step 5: Code Quality Reviewer Prompt Template
+
+```markdown
+## Code Quality Review
+
+### Files to Review
+[List of changed files with line ranges]
+
+### Project Conventions
+- Python with `from __future__ import annotations`
+- DB via `from tools.db.storage import get_connection`
+- Audit via `log_forge_event()` or audit_trail INSERT
+- UUIDs: `uuid.uuid4().hex`
+- Timestamps: `datetime.now(timezone.utc).isoformat()`
+- CUI marking: `# CUI // SP-CTI` on line 1 of new files
+- PostgreSQL compatible (BOOLEAN DEFAULT FALSE, not DEFAULT 0)
+
+### Review Checklist
+1. Follows codebase patterns and conventions?
+2. No security vulnerabilities (injection, XSS, eval)?
+3. Tests are meaningful (test behavior, not implementation)?
+4. Error handling appropriate?
+5. No magic numbers or unclear naming?
+6. Audit trail entries for state changes?
+
+### Output Format
+- ✅ Approved — code quality good
+- ❌ Issues:
+  - [Category]: [Description] (file:line)
+```
+
+### Step 6: After All Tasks Complete
+
+1. Dispatch a FINAL reviewer subagent across the entire implementation
+2. Run full verification (`goals/verification_iron_law.md`)
+3. Update TodoWrite — all tasks completed
+
+---
+
+## Red Flags — STOP
+
+- Skipping spec review ("code looks good, skip to quality")
+- Skipping quality review ("spec passed, we're done")
+- Not re-reviewing after fixes ("they said they fixed it")
+- Dispatching multiple implementer subagents in parallel on dependent tasks
+- Letting implementer self-review replace actual review
+- Proceeding with unfixed issues
+- Starting code quality review before spec compliance is approved
+
+---
+
+## When Subagent Fails
+
+- **Asks questions:** Answer clearly and completely, re-dispatch
+- **Can't complete task:** Dispatch a FIX subagent with specific instructions. Don't fix manually (context pollution)
+- **Review finds issues:** Implementer fixes, reviewer re-reviews. Repeat until approved.
+- **3+ review loops:** Stop. The task spec may be unclear. Revisit the plan.
+
+---
+
+## Efficiency Notes
+
+**Cost:** More subagent invocations (implementer + 2 reviewers per task).
+**Benefit:** Catches issues early. Cheaper than debugging later. Prevents scope creep (YAGNI). Ensures codebase consistency.
+
+**Optimization:** For trivial tasks (single-line changes, config updates), the orchestrator can combine spec + quality review into a single pass.
+
+---
+
+## Integration
+
+| Related Goal | Relationship |
+|-------------|-------------|
+| `bite_sized_plans.md` | Creates the plans this goal executes |
+| `verification_iron_law.md` | Final verification after all tasks |
+| `systematic_debugging.md` | Used when implementation hits bugs |
+| `brainstorming_gate.md` | Design must be approved before plans are written |
+| `tdd_workflow.md` | Each implementer subagent follows TDD |

goals/systematic_debugging.md

@@ -0,0 +1,257 @@
+# Goal: Systematic Debugging
+
+## Description
+
+Debug any issue using a 4-phase root cause methodology. Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+
+**Adapted from:** [obra/superpowers](https://github.com/obra/superpowers) systematic-debugging skill.
+
+**The iron rule:** NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. If you haven't completed Phase 1, you cannot propose fixes.
+
+---
+
+## When to Use
+
+Use for ANY technical issue:
+- Test failures
+- Bugs in production or development
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+- Dashboard errors (500s, console errors)
+- Database migration failures
+
+**Use ESPECIALLY when:**
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You've already tried multiple fixes
+- Previous fix didn't work
+- You don't fully understand the issue
+
+---
+
+## Prerequisites
+
+- [ ] Issue clearly described (error message, stack trace, or observed behavior)
+- [ ] `memory/MEMORY.md` loaded (session context)
+- [ ] Access to relevant source files and logs
+
+---
+
+## Process
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+#### Step 1.1: Read Error Messages Carefully
+
+- Don't skip past errors or warnings
+- Read stack traces COMPLETELY
+- Note line numbers, file paths, error codes
+- Check for the exact error message — it often contains the solution
+
+#### Step 1.2: Reproduce Consistently
+
+- Can you trigger it reliably?
+- What are the exact steps?
+- Does it happen every time?
+- If not reproducible → gather more data, don't guess
+
+#### Step 1.3: Check Recent Changes
+
+- `git diff` — what changed?
+- Recent commits that could cause this
+- New dependencies, config changes
+- Environmental differences (Python version, DB backend, OS)
+
+#### Step 1.4: Gather Evidence in Multi-Component Systems
+
+When the system has multiple layers (dashboard → API → tool → database):
+
+```
+For EACH component boundary:
+  - Log what data enters the component
+  - Log what data exits the component
+  - Verify environment/config propagation
+  - Check state at each layer
+
+Run once to gather evidence showing WHERE it breaks
+THEN analyze evidence to identify the failing component
+THEN investigate that specific component
+```
+
+**Example (ICDEV stack):**
+```bash
+# Layer 1: Dashboard template — does the JS call the right endpoint?
+# Layer 2: Flask route in app.py — does it receive correct params?
+# Layer 3: Tool function — does it return expected structure?
+# Layer 4: Database — does the query return data?
+```
+
+#### Step 1.5: Trace Data Flow
+
+- Where does the bad value originate?
+- What called this with the bad value?
+- Keep tracing up until you find the source
+- Fix at source, not at symptom
+
+**Tools available:**
+```bash
+python tools/testing/health_check.py --json          # System health
+python tools/db/storage.py --health --json            # DB connectivity
+python tools/monitor/log_analyzer.py --tail 50        # Recent logs
+```
+
+---
+
+### Phase 2: Pattern Analysis
+
+#### Step 2.1: Find Working Examples
+
+- Locate similar working code in same codebase
+- What works that's similar to what's broken?
+- Compare function signatures, DB schemas, API patterns
+
+#### Step 2.2: Compare Against References
+
+- If implementing a pattern, read the reference implementation COMPLETELY
+- Don't skim — read every line
+- Understand the pattern fully before applying
+
+#### Step 2.3: Identify Differences
+
+- What's different between working and broken?
+- List every difference, however small
+- Don't assume "that can't matter"
+
+**Common ICDEV-specific patterns to check:**
+- PostgreSQL vs SQLite placeholder mismatch (`?` vs `%s` — handled by StorageConnection)
+- BOOLEAN DEFAULT 0 vs DEFAULT FALSE (PostgreSQL incompatibility)
+- Missing `ensure_*_tables()` call before first DB access
+- API endpoint signature mismatch between `app.py` route and tool function
+- Template API path not matching Flask route
+
+---
+
+### Phase 3: Hypothesis and Testing
+
+#### Step 3.1: Form Single Hypothesis
+
+- State clearly: "I think X is the root cause because Y"
+- Be specific, not vague
+
+#### Step 3.2: Test Minimally
+
+- Make the SMALLEST possible change to test hypothesis
+- One variable at a time
+- Don't fix multiple things at once
+
+#### Step 3.3: Verify Before Continuing
+
+- Did it work? Yes → Phase 4
+- Didn't work? Form NEW hypothesis
+- DON'T add more fixes on top
+
+#### Step 3.4: When You Don't Know
+
+- Say "I don't understand X"
+- Don't pretend to know
+- Ask the user for help
+- Research more
+
+---
+
+### Phase 4: Implementation
+
+#### Step 4.1: Create Failing Test Case
+
+- Simplest possible reproduction
+- Automated test if possible (pytest)
+- One-off script if no framework applies
+- MUST have before fixing
+
+**Tool:** `python tools/builder/test_writer.py --project <name> --requirement "<bug description>"`
+
+#### Step 4.2: Implement Single Fix
+
+- Address the ROOT CAUSE identified
+- ONE change at a time
+- No "while I'm here" improvements
+- No bundled refactoring
+
+#### Step 4.3: Verify Fix
+
+- Test passes now?
+- No other tests broken?
+- Issue actually resolved?
+- Run: `python tools/testing/health_check.py --json`
+
+#### Step 4.4: If Fix Doesn't Work — STOP
+
+Count: How many fixes have you tried?
+
+- **If < 3:** Return to Phase 1, re-analyze with new information
+- **If ≥ 3:** STOP and question the architecture
+
+**3+ failed fixes = architectural problem:**
+- Each fix reveals new shared state/coupling/problem in different place
+- Fixes require "massive refactoring" to implement
+- Each fix creates new symptoms elsewhere
+
+**Discuss with user before attempting more fixes.**
+
+#### Step 4.5: Log the Fix
+
+```bash
+python tools/memory/memory_write.py --content "Bug: <description>. Root cause: <cause>. Fix: <what changed>." --type insight --importance 6
+```
+
+---
+
+## Red Flags — STOP and Return to Phase 1
+
+If you catch yourself thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "One more fix attempt" (when already tried 2+)
+- Proposing solutions before tracing data flow
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+---
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
+| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check. |
+| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
+| "I'll write test after confirming fix" | Untested fixes don't stick. Test first proves it. |
+| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
+| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
+
+---
+
+## Quick Reference
+
+| Phase | Key Activities | Success Criteria |
+|-------|---------------|------------------|
+| **1. Root Cause** | Read errors, reproduce, check changes, trace data | Understand WHAT and WHY |
+| **2. Pattern** | Find working examples, compare differences | Identify what's different |
+| **3. Hypothesis** | Form theory, test minimally, one variable | Confirmed or new hypothesis |
+| **4. Implementation** | Create test, fix root cause, verify | Bug resolved, tests pass |
+
+---
+
+## Compliance Integration
+
+- All bug fixes MUST be logged to audit trail (NIST AU-3)
+- Security bugs require `python tools/security/sast_runner.py` re-scan after fix
+- If fix changes compliance posture, re-run crosswalk: `python tools/compliance/crosswalk_engine.py --control <affected-control>`