ac-framework 1.9.2 → 1.9.3

package/framework/new_project/.roo/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: systematic-debugging
+description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+---
+
+# Systematic Debugging
+
+## Overview
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+**Violating the letter of this process is violating the spirit of debugging.**
+
+## The Iron Law
+
+```
+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
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+
+**Use this 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
+
+**Don't skip when:**
+- Issue seems simple (simple bugs have root causes too)
+- You're in a hurry (rushing guarantees rework)
+- Manager wants it fixed NOW (systematic is faster than thrashing)
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully**
+   - Don't skip past errors or warnings
+   - They often contain the exact solution
+   - Read stack traces completely
+   - Note line numbers, file paths, error codes
+
+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
+
+3. **Check Recent Changes**
+   - What changed that could cause this?
+   - Git diff, recent commits
+   - New dependencies, config changes
+   - Environmental differences
+
+4. **Gather Evidence in Multi-Component Systems**
+
+   **WHEN system has multiple components (CI → build → signing, API → service → database):**
+
+   **BEFORE proposing fixes, add diagnostic instrumentation:**
+   ```
+   For EACH component boundary:
+     - Log what data enters component
+     - Log what data exits component
+     - Verify environment/config propagation
+     - Check state at each layer
+
+   Run once to gather evidence showing WHERE it breaks
+   THEN analyze evidence to identify failing component
+   THEN investigate that specific component
+   ```
+
+   **Example (multi-layer system):**
+   ```bash
+   # Layer 1: Workflow
+   echo "=== Secrets available in workflow: ==="
+   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
+
+   # Layer 2: Build script
+   echo "=== Env vars in build script: ==="
+   env | grep IDENTITY || echo "IDENTITY not in environment"
+
+   # Layer 3: Signing script
+   echo "=== Keychain state: ==="
+   security list-keychains
+   security find-identity -v
+
+   # Layer 4: Actual signing
+   codesign --sign "$IDENTITY" --verbose=4 "$APP"
+   ```
+
+   **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)
+
+5. **Trace Data Flow**
+
+   **WHEN error is deep in call stack:**
+
+   See `root-cause-tracing.md` in this directory for the complete backward tracing technique.
+
+   **Quick version:**
+   - Where does bad value originate?
+   - What called this with bad value?
+   - Keep tracing up until you find the source
+   - Fix at source, not at symptom
+
+### Phase 2: Pattern Analysis
+
+**Find the pattern before fixing:**
+
+1. **Find Working Examples**
+   - Locate similar working code in same codebase
+   - What works that's similar to what's broken?
+
+2. **Compare Against References**
+   - If implementing pattern, read reference implementation COMPLETELY
+   - Don't skim - read every line
+   - Understand the pattern fully before applying
+
+3. **Identify Differences**
+   - What's different between working and broken?
+   - List every difference, however small
+   - Don't assume "that can't matter"
+
+4. **Understand Dependencies**
+   - What other components does this need?
+   - What settings, config, environment?
+   - What assumptions does it make?
+
+### Phase 3: Hypothesis and Testing
+
+**Scientific method:**
+
+1. **Form Single Hypothesis**
+   - State clearly: "I think X is the root cause because Y"
+   - Write it down
+   - Be specific, not vague
+
+2. **Test Minimally**
+   - Make the SMALLEST possible change to test hypothesis
+   - One variable at a time
+   - Don't fix multiple things at once
+
+3. **Verify Before Continuing**
+   - Did it work? Yes → Phase 4
+   - Didn't work? Form NEW hypothesis
+   - DON'T add more fixes on top
+
+4. **When You Don't Know**
+   - Say "I don't understand X"
+   - Don't pretend to know
+   - Ask for help
+   - Research more
+
+### Phase 4: Implementation
+
+**Fix the root cause, not the symptom:**
+
+1. **Create Failing Test Case**
+   - Simplest possible reproduction
+   - Automated test if possible
+   - One-off test script if no framework
+   - MUST have before fixing
+   - Use the `superpowers:test-driven-development` skill for writing proper failing tests
+
+2. **Implement Single Fix**
+   - Address the root cause identified
+   - ONE change at a time
+   - No "while I'm here" improvements
+   - No bundled refactoring
+
+3. **Verify Fix**
+   - Test passes now?
+   - No other tests broken?
+   - Issue actually resolved?
+
+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 (step 5 below)**
+   - DON'T attempt Fix #4 without architectural discussion
+
+5. **If 3+ Fixes Failed: Question Architecture**
+
+   **Pattern indicating 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
+
+   **STOP and question fundamentals:**
+   - Is this pattern fundamentally sound?
+   - Are we "sticking with it through sheer inertia"?
+   - Should we refactor architecture vs. continue fixing symptoms?
+
+   **Discuss with your human partner before attempting more fixes**
+
+   This is NOT a failed hypothesis - this is a wrong architecture.
+
+## Red Flags - STOP and Follow Process
+
+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"
+- "Pattern says X but I'll adapt it differently"
+- "Here are the main problems: [lists fixes without investigation]"
+- Proposing solutions before tracing data flow
+- **"One more fix attempt" (when already tried 2+)**
+- **Each fix reveals new problem in different place**
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+**If 3+ fixes failed:** Question the architecture (see Phase 4.5)
+
+## your human partner's Signals You're Doing It Wrong
+
+**Watch for these redirections:**
+- "Is that not happening?" - You assumed without verifying
+- "Will it show us...?" - You should have added evidence gathering
+- "Stop guessing" - You're proposing fixes without understanding
+- "Ultrathink this" - Question fundamentals, not just symptoms
+- "We're stuck?" (frustrated) - Your approach isn't working
+
+**When you see these:** 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 thrashing. |
+| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
+| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
+| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
+| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
+| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
+| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
+
+## Quick Reference
+
+| Phase | Key Activities | Success Criteria |
+|-------|---------------|------------------|
+| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
+| **2. Pattern** | Find working examples, compare | Identify differences |
+| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
+| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
+
+## When Process Reveals "No Root Cause"
+
+If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
+
+1. You've completed the process
+2. Document what you investigated
+3. Implement appropriate handling (retry, timeout, error message)
+4. Add monitoring/logging for future investigation
+
+**But:** 95% of "no root cause" cases are incomplete investigation.
+
+## Supporting Techniques
+
+These techniques are part of systematic debugging and available in this directory:
+
+- **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger
+- **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause
+- **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
+
+**Related skills:**
+- **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1)
+- **superpowers:verification-before-completion** - Verify fix worked before claiming success
+
+## Real-World Impact
+
+From debugging sessions:
+- Systematic approach: 15-30 minutes to fix
+- Random fixes approach: 2-3 hours of thrashing
+- First-time fix rate: 95% vs 40%
+- New bugs introduced: Near zero vs common

package/framework/new_project/.trae/skills/acfm-memory/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: acfm-memory
+description: Autonomous memory system for persistent learning across sessions. Automatically saves architectural decisions, bugfixes, patterns, and insights. Use to recall context from previous work and build institutional knowledge.
+---
+
+# AC Framework Memory System
+
+## Overview
+
+The AC Framework Memory System provides **autonomous persistent memory** for AI agents. It automatically detects and saves valuable knowledge during development, then recalls relevant context when needed.
+
+**Key Capabilities:**
+- **Automatic saving**: Detects and stores important decisions, patterns, and solutions
+- **Full-text search**: Find relevant memories instantly
+- **Context recall**: Get relevant knowledge before starting tasks
+- **Pattern analysis**: Detect recurring themes and errors
+- **Timeline view**: See chronological context around any memory
+
+## When to Use This Skill
+
+### Before Starting Work
+- **Recall relevant context**: `acfm memory recall "<task description>"`
+- **Check for similar changes**: `acfm memory search "<topic>"`
+- **Review patterns**: `acfm memory patterns`
+
+### During Work (Automatic)
+The agent automatically saves memories when:
+- Completing architectural proposals
+- Fixing bugs (especially after multiple attempts)
+- Refactoring code successfully
+- Optimizing performance
+- Discovering important patterns
+
+### After Work
+- **Review learnings**: `acfm memory stats`
+- **Export for sharing**: `acfm memory export team-memory.json`
+- **Find gaps**: `acfm memory patterns --min-frequency 1`
+
+## Memory Types
+
+| Type | Description | Auto-Trigger |
+|------|-------------|--------------|
+| `architectural_decision` | Major design decisions | After proposal/design |
+| `bugfix_pattern` | Solutions to bugs | After fixing error |
+| `refactor_technique` | Successful refactoring patterns | After refactor |
+| `performance_insight` | Optimization learnings | After performance work |
+| `security_fix` | Security vulnerability fixes | After security patch |
+| `api_pattern` | API design patterns | After API work |
+| `convention` | Project conventions | After establishing pattern |
+| `workaround` | Temporary solutions | After implementing hack |
+| `context_boundary` | System limitations | After defining boundaries |
+
+## Commands
+
+### Core Commands
+
+#### Initialize Memory System
+```bash
+acfm memory init
+```
+Creates the SQLite database at `~/.acfm/memory.db`.
+
+#### Save Memory (Manual)
+```bash
+acfm memory save "Descripción de la decisión o patrón" \
+  --type architectural_decision \
+  --importance high \
+  --tags "react,performance"
+```
+
+#### Recall Context
+```bash
+# For specific task
+acfm memory recall "implementing authentication"
+
+# For current project (general context)
+acfm memory recall
+```
+
+#### Search Memories
+```bash
+# Basic search
+acfm memory search "JWT"
+
+# Filtered search
+acfm memory search "database" --type architectural_decision --importance high
+```
+
+### Advanced Commands
+
+#### Timeline View
+```bash
+acfm memory timeline <memory-id>
+```
+Shows what happened before and after a specific memory.
+
+#### Connections
+```bash
+acfm memory connections <memory-id> --depth 2
+```
+Shows related memories as a graph.
+
+#### Pattern Detection
+```bash
+acfm memory patterns
+acfm memory patterns --type bugfix_pattern
+```
+Finds recurring topics and frequent error types.
+
+#### Predictive Recall
+```bash
+acfm memory anticipate "caching strategy"
+```
+Predicts which memories will be relevant for a future task.
+
+#### Statistics
+```bash
+acfm memory stats
+acfm memory stats --project /path/to/project
+```
+
+#### Export/Import
+```bash
+# Export for sharing
+acfm memory export team-memory.json
+
+# Import shared knowledge
+acfm memory import team-memory.json
+```
+
+## Auto-Save Behavior
+
+### What Triggers Auto-Save
+
+The agent evaluates content using a confidence score (0-1):
+
+**High confidence triggers (auto-save):**
+- Contains decision keywords: "decidimos", "optamos", "mejor usar"
+- Describes solution to problem
+- Contains architectural guidance
+- Has error + solution pair
+- Takes >10 minutes to resolve
+
+**Low confidence (skip):**
+- Very short content (<50 chars)
+- Contains specific IDs/UUIDs
+- Temporary TODOs
+- Obvious/common knowledge
+
+### Confidence Scoring
+
+```
+Base: 0.5
++ Decision keywords: +0.25
++ Contains solution: +0.20
++ Bug fix: +0.15
++ Architecture: +0.20
++ Optimization: +0.15
++ Security: +0.25
+- Too short: -0.20
+- Specific IDs: -0.15
+- TODO/FIXME: -0.20
+
+Threshold for auto-save: 0.60
+```
+
+### Notification
+
+When auto-saving, the agent will display:
+```
+💾 Memory saved: [Brief description of what was learned]
+   Type: bugfix_pattern | Confidence: 85%
+```
+
+## Privacy
+
+Content between `<private>` tags is automatically redacted:
+
+```markdown
+Decidimos usar AWS para hosting. <private>Usaremos la cuenta
+producción-env-123</private> para el deployment.
+```
+
+Saved as:
+```
+Decidimos usar AWS para hosting. [REDACTED PRIVATE CONTENT]
+```
+
+## Integration with Spec Workflow
+
+### Before Creating Artifacts
+
+When you request `acfm spec instructions`, the system automatically:
+
+1. Queries memories related to the change topic
+2. Includes relevant memories in the response
+3. Displays them as context for the agent
+
+Example output:
+```json
+{
+  "instruction": "...",
+  "relevantMemories": [
+    {
+      "id": 42,
+      "type": "architectural_decision",
+      "content": "Previous auth system used JWT...",
+      "importance": "high"
+    }
+  ]
+}
+```
+
+### During Apply Phase
+
+When implementing tasks, the system recalls:
+- Patterns from similar previous tasks
+- Bugfixes related to current work
+- Performance insights for optimization tasks
+
+## Best Practices
+
+### For Agents
+
+1. **Always recall before starting**: Check `acfm memory recall` for relevant context
+2. **Let auto-save work**: Don't manually save everything - trust the confidence scoring
+3. **Use topic keys**: When manually saving, use consistent topic keys for deduplication
+4. **Mark importance**: Critical decisions should be marked `critical` or `high`
+5. **Add tags**: Tags improve searchability
+
+### For Users
+
+1. **Initialize once**: Run `acfm memory init` per machine
+2. **Review periodically**: Check `acfm memory stats` to see what's been learned
+3. **Export regularly**: Share knowledge with team via `acfm memory export`
+4. **Prune old data**: Use `acfm memory prune` to archive obsolete memories
+5. **Use private tags**: Mark sensitive content with `<private>` tags
+
+## Examples
+
+### Example 1: Bug Fix
+
+**Agent fixes an authentication bug:**
+```
+💾 Memory saved: JWT refresh token fails when expired during request
+   Type: bugfix_pattern | Confidence: 87%
+   Solution: Implement token refresh interceptor
+```
+
+**Later, similar task:**
+```bash
+$ acfm memory recall "authentication token"
+→ [Memory #42] JWT refresh token fails when expired...
+```
+
+### Example 2: Architectural Decision
+
+**Agent completes proposal:**
+```
+💾 Memory saved: Microservices architecture chosen for scalability
+   Type: architectural_decision | Confidence: 92%
+   Tags: ["architecture", "microservices", "scalability"]
+```
+
+**Weeks later, new service:**
+```bash
+$ acfm memory search "microservices" --type architectural_decision
+→ [Memory #15] Microservices architecture chosen for scalability
+```
+
+### Example 3: Pattern Detection
+
+```bash
+$ acfm memory patterns --type bugfix_pattern
+
+Detected patterns:
+- null-check-react (3×) - Null checks in React components
+- async-race-condition (2×) - Race conditions in async code
+- cors-preflight (2×) - CORS preflight issues
+
+Recommendation: Consider adding ESLint rules for null checks
+```
+
+## Troubleshooting
+
+### Memory not saving
+- Check initialization: `acfm memory init`
+- Content may be below confidence threshold
+- May contain too many specific IDs
+
+### Search not finding results
+- Try broader keywords
+- Use `acfm memory recall` without query for general context
+- Check if memories exist: `acfm memory stats`
+
+### Database locked
+- Close other instances of `acfm`
+- SQLite is single-writer; wait a moment and retry
+
+## Related Skills
+
+- `acfm-spec-workflow` - Foundation for spec-driven development
+- `context-synthesizer` - For managing context in long conversations
+- `systematic-debugging` - For complex problem resolution
+
+## CLI Reference
+
+See `acfm memory --help` for all commands and options.
+
+---
+
+**Remember**: The memory system learns from every interaction. The more you use it, the more valuable it becomes.