@exaudeus/workrail 3.12.0 → 3.13.0

package/workflows/bug-investigation.json

@@ -1,112 +0,0 @@
-{
-  "id": "bug-investigation",
-  "name": "Bug Investigation",
-  "version": "1.0.0",
-  "description": "A systematic bug investigation workflow that finds the true source of bugs through strategic planning and evidence-based analysis. Guides agents through plan-then-execute phases to avoid jumping to conclusions.",
-  "clarificationPrompts": [
-    "What type of system is this? (web app, backend service, CLI tool, etc.)",
-    "How reproducible is this bug? (always, sometimes, rarely)",
-    "What access do you have? (full codebase, logs, tests, etc.)"
-  ],
-  "preconditions": [
-    "User has a specific bug or failing test to investigate",
-    "Agent has codebase access and can run tests/build",
-    "Bug is reproducible with specific steps"
-  ],
-  "metaGuidance": [
-    "WHO YOU ARE: You are a special investigator - one of the few who has the patience, determination, and skill to find the TRUE source of bugs.",
-    "Most investigators stop at the obvious explanation. You don't. You look past red herrings, challenge assumptions, and dig until you have certainty.",
-    "YOUR MISSION: Find the REAL cause of this bug. Not the apparent cause, not the first explanation, but the actual source with evidence to prove it.",
-    "WHY THIS WORKFLOW EXISTS: It gives you a systematic process to avoid the traps that catch other investigators - jumping to conclusions, confirmation bias, surface-level analysis.",
-    "HOW IT WORKS: Each phase has two steps: First you PLAN your approach (think strategically), then you EXECUTE it (do the work).",
-    "This planning step is critical - it forces you to think about HOW you'll investigate before diving in. Better plans lead to better investigations.",
-    "THE PHASES:",
-    "Phase 0: Understand what you're investigating and set up your workspace",
-    "Phase 1: Trace how execution flows from entry point to error (follow the code path)",
-    "Phase 2: Form multiple hypotheses about what could be causing this (stay open-minded)",
-    "Phase 3: Design and add instrumentation to gather evidence (set up your surveillance)",
-    "Phase 4: Run instrumented code and collect evidence (gather proof, not assumptions)",
-    "Phase 5: Validate your conclusion rigorously (be your harshest critic)",
-    "Phase 6: Document your findings so others can understand and fix it (prove your case)",
-    "CRITICAL DISTINCTION - THEORY VS PROOF:",
-    "When you read code and think 'I found it!', you have a THEORY. Theories feel certain but are often wrong.",
-    "PROOF comes from running instrumented code, collecting evidence, ruling out alternatives, and validating rigorously.",
-    "You must complete all phases to get from theory to proof. No shortcuts, even with high confidence.",
-    "YOUR DELIVERABLE: A diagnostic writeup that proves you found the true source - complete with evidence, alternative explanations ruled out, and reproduction steps.",
-    "SUCCESS MEANS: Someone reading your writeup can fix the bug confidently because you've proven what's actually happening and why.",
-    "WORKFLOW MECHANICS: Call workflow_next to get each phase. Complete the phase (both plan and execute). Call workflow_next again. Repeat until isComplete=true."
-  ],
-  "steps": [
-    {
-      "id": "phase-0-setup",
-      "title": "Phase 0: Investigation Setup",
-      "prompt": "**UNDERSTAND THE PROBLEM & SET UP YOUR WORKSPACE**\n\nBefore you start investigating, you need to understand what you're looking for and prepare your workspace.\n\n**Your Task**: Set up everything you need for a systematic investigation.\n\n**Questions to Answer**:\n- What exactly is the reported problem?\n- What's the expected vs actual behavior?\n- How is it reproduced?\n- What error messages or symptoms exist?\n- What information do you have (logs, stack traces, etc.)?\n- What tools and access do you have?\n- What workspace do you need (branch, investigation directory)?\n\n**Set Up**:\n- Create INVESTIGATION_CONTEXT.md to track your investigation\n- Document the bug description and reproduction steps\n- Note any initial assumptions you'll need to verify\n- Set up a workspace (branch or directory) if appropriate\n- Clarify any user preferences\n\n**OUTPUT**: INVESTIGATION_CONTEXT.md with:\n- Clear description of the bug\n- Reproduction steps\n- Initial information (stack traces, logs, errors)\n- Your workspace location\n- Any early assumptions to verify later\n\n**Before Proceeding**: Can you clearly explain this bug to someone else? Do you know how to reproduce it?",
-      "agentRole": "You are beginning your investigation. Take time to understand what you're looking for before you start looking.",
-      "requireConfirmation": false
-    },
-    {
-      "id": "phase-1a-plan",
-      "title": "Phase 1A: Plan Your Investigation Approach",
-      "prompt": "**PLAN HOW YOU'LL TRACK DOWN THIS BUG**\n\nYou're about to analyze the codebase. But first, think strategically about HOW you'll investigate.\n\n**Think Through**:\n\n1. **Where does execution start?**\n   - What triggers this bug? (API call, user action, test, scheduled job?)\n   - Where in the code does execution begin?\n\n2. **What's your investigation strategy?**\n   - Will you trace execution flow from entry to error?\n   - Will you start at the error and work backwards?\n   - Will you examine recent changes first?\n   - How will you identify the key points to investigate?\n\n3. **What could cause you to miss the real issue?**\n   - Focusing too narrowly on one area?\n   - Missing indirect causes or side effects?\n   - Assuming things work as documented?\n   - Not checking alternative execution paths?\n\n4. **What's your analysis plan?**\n   - List the sequence of investigations you'll do\n   - What will you look for at each step?\n   - How will you know when you understand enough?\n\n**OUTPUT**: Update INVESTIGATION_CONTEXT.md with \"Phase 1 Investigation Plan\" section:\n- Your investigation strategy\n- Sequence of steps you'll take\n- Key questions you need to answer\n- Risks you're watching out for\n\n**Self-Check**: Is your plan specific enough to follow? Does it account for the ways you might miss the real cause?",
-      "agentRole": "You are a strategic investigator planning your approach. Think before you dive in.",
-      "requireConfirmation": false
-    },
-    {
-      "id": "phase-1b-execute",
-      "title": "Phase 1B: Execute Your Investigation",
-      "prompt": "**CARRY OUT YOUR INVESTIGATION PLAN**\n\nNow execute the investigation strategy you designed.\n\n**Execute Your Plan**:\n- Follow the sequence of investigations you planned\n- Trace execution flow from entry point to error\n- Track how data flows and state changes\n- Read the actual code at key points\n- Note anything suspicious or unexpected\n- Adapt your plan if you discover new information\n\n**Document As You Go**:\nCreate ExecutionFlow.md with:\n- **Entry Point**: Where execution begins\n- **Call Chain**: Step-by-step path from entry to error (with file:line)\n- **Data Flow**: How data transforms along the way\n- **State Changes**: What gets modified\n- **Suspicious Points**: Code that could be problematic\n- **Patterns**: How things normally work vs how they work in failing case\n\n**Self-Critique**:\n- Did you follow your plan or skip steps?\n- Did you actually trace the execution flow, or just read code?\n- What did you learn that surprised you?\n- What are you still uncertain about?\n- Did your plan work, or should you investigate differently?\n\n**Critical Reminder**: You're building understanding of what the code DOES. You don't have a diagnosis yet - that comes later after you form and test hypotheses.",
-      "agentRole": "You are executing your investigation plan. Stay systematic and document what you find.",
-      "requireConfirmation": false
-    },
-    {
-      "id": "phase-2a-plan",
-      "title": "Phase 2A: Plan Your Hypothesis Development",
-      "prompt": "**PLAN HOW YOU'LL FORM HYPOTHESES**\n\nBased on your investigation, you'll now develop hypotheses about what's causing the bug.\n\n**Think Through**:\n\n1. **What patterns did you notice?**\n   - From your execution flow tracing, what stood out?\n   - What code seemed suspicious?\n   - What assumptions are baked into the code?\n\n2. **What types of causes should you consider?**\n   - Logic errors in the code?\n   - Data issues (wrong format, corruption, missing)?\n   - Timing or race conditions?\n   - Environment or configuration issues?\n   - Integration problems with dependencies?\n\n3. **How will you avoid anchoring on your first idea?**\n   - How many alternative hypotheses will you generate?\n   - How will you challenge your initial impressions?\n   - What evidence would contradict your leading theory?\n\n4. **What makes a good hypothesis?**\n   - Specific enough to test\n   - Explains all the symptoms\n   - Has clear evidence for/against\n   - Can be proven or disproven\n\n**OUTPUT**: Update INVESTIGATION_CONTEXT.md with \"Phase 2 Hypothesis Strategy\":\n- How you'll generate multiple hypotheses\n- What types of causes you'll consider\n- How you'll avoid confirmation bias\n- How you'll test your hypotheses\n\n**Self-Check**: Are you committed to generating multiple hypotheses, or are you already attached to one idea?",
-      "agentRole": "You are strategizing about hypothesis formation. Commit to staying open-minded.",
-      "requireConfirmation": false
-    },
-    {
-      "id": "phase-2b-execute",
-      "title": "Phase 2B: Develop and Prioritize Hypotheses",
-      "prompt": "**FORM MULTIPLE HYPOTHESES ABOUT THE BUG**\n\nNow generate your hypotheses following your strategy.\n\n**Generate Hypotheses**:\n\nFor each possible cause, create a hypothesis:\n\n**Hypothesis Template**:\n- **ID**: H1, H2, H3, etc.\n- **Statement**: \"The bug occurs because [specific cause]\"\n- **Evidence For**: What from your investigation supports this?\n- **Evidence Against**: What contradicts this or makes it unlikely?\n- **How to Test**: What evidence would prove/disprove this?\n- **Likelihood** (1-10): Based on current evidence\n\n**Generate 3-7 hypotheses**. Force yourself to consider alternatives even if one seems obvious.\n\n**Prioritize**:\nRank by:\n1. Likelihood (evidence strength)\n2. Testability (can you validate it?)\n3. Completeness (explains all symptoms?)\n\n**Plan Validation**:\nFor top 3-5 hypotheses:\n- What instrumentation would prove/disprove each?\n- What tests should you run?\n- What experiments could distinguish between them?\n\n**OUTPUT**: Create Hypotheses.md with all hypotheses, rankings, and validation strategy.\n\n**🚨 CRITICAL - YOU ARE NOT DONE:**\n\nYou now have theories. You do NOT have proof.\n\nEven if H1 has 10/10 likelihood, it's based on reading code, not evidence from running code.\n\nYou MUST continue to Phase 3 (design instrumentation) and Phase 4 (collect evidence).\n\nThis is not optional. High confidence without evidence = educated guess, not diagnosis.\n\nCall workflow_next to continue.",
-      "agentRole": "You are forming competing hypotheses. Stay open to alternatives even if one seems obvious.",
-      "requireConfirmation": false
-    },
-    {
-      "id": "phase-3a-plan",
-      "title": "Phase 3A: Design Your Instrumentation Strategy",
-      "prompt": "**PLAN HOW YOU'LL GATHER EVIDENCE**\n\nYou have hypotheses. Now design how you'll gather evidence to test them.\n\n**Think Through**:\n\n1. **What evidence would prove each hypothesis?**\n   - For H1, what specific data points would confirm it?\n   - For H2, what would you observe if it's correct?\n   - How can you distinguish between competing hypotheses?\n\n2. **Where should you add instrumentation?**\n   - What points in the execution flow are critical?\n   - Where could you observe the data/state you need?\n   - What's already being logged vs what do you need to add?\n\n3. **What's the right level of detail?**\n   - Too much logging = noise and hard to analyze\n   - Too little = gaps and missing evidence\n   - How will you balance this?\n\n4. **Can you use existing tests?**\n   - Are there tests you can enhance instead of adding new logging?\n   - Can you modify tests to expose the state you need?\n   - Should you write new targeted tests?\n\n**OUTPUT**: Update INVESTIGATION_CONTEXT.md with \"Phase 3 Instrumentation Plan\":\n- What evidence you need for each hypothesis\n- Where you'll add instrumentation (file:line)\n- What you'll log/observe at each point\n- Test scenarios you'll prepare\n- How you'll organize output to distinguish hypotheses\n\n**Self-Check**: Will this instrumentation actually give you the evidence you need? What might you miss?",
-      "agentRole": "You are designing your evidence collection strategy. Think carefully about what you need to prove.",
-      "requireConfirmation": false
-    },
-    {
-      "id": "phase-3b-execute",
-      "title": "Phase 3B: Implement Your Instrumentation",
-      "prompt": "**ADD INSTRUMENTATION AND PREPARE TEST SCENARIOS**\n\nNow implement the instrumentation strategy you designed.\n\n**Implement**:\n- Add debug logging at the points you identified\n- Enhance or create tests to expose necessary state\n- Add assertions to catch violations\n- Set up controlled experiments if needed\n- Label everything clearly ([H1], [H2], etc.)\n\n**Prepare Test Scenarios**:\n- Minimal reproduction case\n- Edge cases that might behave differently\n- Working scenarios for comparison\n- Variations that test specific hypotheses\n\n**OUTPUT**: Update INVESTIGATION_CONTEXT.md with:\n- List of instrumentation added (what/where/why)\n- Test scenarios prepared\n- Expected outcomes for each hypothesis\n- How you'll analyze results\n\n**Self-Critique**:\n- Did you add the instrumentation you planned?\n- Did you skip any because it seemed unnecessary?\n- Is your instrumentation labeled clearly?\n- Are your test scenarios sufficient?\n\n**Readiness Check**: If you run these tests, will you get the evidence you need to prove/disprove your hypotheses?",
-      "agentRole": "You are implementing your evidence collection plan. Good instrumentation is the foundation of proof.",
-      "requireConfirmation": false
-    },
-    {
-      "id": "phase-4-execute",
-      "title": "Phase 4: Collect Evidence",
-      "prompt": "**RUN INSTRUMENTED CODE AND COLLECT EVIDENCE**\n\nNow run your test scenarios and collect the evidence.\n\n**Execute**:\n- Run minimal reproduction case\n- Run edge cases and variations\n- Run working scenarios for comparison\n- Capture all output (logs, errors, test results)\n\n**Organize Evidence**:\nFor each hypothesis, create Evidence_H1.md, Evidence_H2.md, etc.:\n- What did the instrumentation reveal?\n- Does behavior match predictions?\n- What unexpected findings emerged?\n- Quality rating (1-10): How strong is this evidence?\n\n**Analyze Patterns**:\n- Which hypotheses are supported by evidence?\n- Which are contradicted?\n- Are there patterns you didn't predict?\n- Do you need different instrumentation?\n- Should you form new hypotheses?\n\n**Update Hypotheses**:\nUpdate Hypotheses.md with:\n- Evidence collected for each\n- New likelihood scores based on evidence\n- Evidence quality ratings\n- New insights or remaining questions\n\n**Decision Point**:\n- Strong evidence (8+/10) for one hypothesis? → Proceed to validation\n- Need more instrumentation? → Go back and add it\n- Need to revise hypotheses? → Update them\n\nBut you're not done until you have strong evidence. Keep investigating.",
-      "agentRole": "You are collecting evidence systematically. Let the data guide you, not your assumptions.",
-      "requireConfirmation": false
-    },
-    {
-      "id": "phase-5-validate",
-      "title": "Phase 5: Validate Your Conclusion",
-      "prompt": "**RIGOROUSLY VALIDATE YOUR FINDING**\n\nYou have a leading hypothesis with evidence. Now be your harshest critic.\n\n**State Your Conclusion**:\n- What hypothesis has the strongest evidence?\n- What's your confidence (1-10)?\n- What evidence supports it?\n\n**Challenge Yourself (Adversarial Review)**:\n\n1. **Alternative Explanations**: What else could explain the evidence you collected?\n2. **Contradicting Evidence**: What evidence doesn't fit your conclusion?\n3. **Bias Check**: Are you seeing what you expect to see?\n4. **Completeness**: Does this explain ALL symptoms, or just some?\n5. **Edge Cases**: Does your explanation hold for all scenarios?\n6. **Reproducibility**: Can you reliably reproduce the bug based on your understanding?\n\n**If confidence < 9/10**:\n- What specific test would raise confidence?\n- What alternative should you rule out?\n- What additional evidence do you need?\n- Go collect that evidence\n\n**Final Assessment**:\nAnswer these YES/NO:\n- Does this explain all observed symptoms?\n- Have you ruled out major alternatives?\n- Can you reproduce the bug based on this understanding?\n- Would you stake your reputation on this diagnosis?\n- Is there any contradicting evidence?\n\n**OUTPUT**: ValidationReport.md with:\n- Leading hypothesis and evidence\n- Alternatives considered and ruled out\n- Adversarial review findings\n- Final confidence score\n- Remaining uncertainties\n\n**Threshold**: 9+/10 confidence with strong evidence to proceed. If not, keep investigating.",
-      "agentRole": "You are validating your conclusion rigorously. Be skeptical of your own findings.",
-      "requireConfirmation": false
-    },
-    {
-      "id": "phase-6-writeup",
-      "title": "Phase 6: Prove Your Case",
-      "prompt": "**DOCUMENT YOUR INVESTIGATION - PROVE YOU FOUND THE TRUE SOURCE**\n\nYou've found the true source of the bug. Now prove it to others.\n\n**Your Task**: Create a diagnostic writeup that proves your case.\n\n**Structure**:\n\n**1. EXECUTIVE SUMMARY** (3-5 sentences)\n- What's the bug?\n- What's the true cause?\n- How confident are you? (should be 9-10/10)\n- What's the impact?\n\n**2. THE TRUE SOURCE** (detailed)\n- Explain the root cause\n- Why this causes the observed symptoms\n- Code locations (file:line)\n- Relevant code snippets\n\n**3. THE PROOF** (your evidence)\n- Key evidence that proves this diagnosis\n- How you collected it (instrumentation, tests)\n- Evidence quality and sources\n- Why alternative explanations don't fit\n\n**4. HOW TO REPRODUCE**\n- Minimal steps to reproduce\n- What to observe that confirms the diagnosis\n- Conditions required\n\n**5. YOUR INVESTIGATION**\n- What you analyzed\n- Hypotheses you tested\n- How you arrived at the conclusion\n- Key turning points\n\n**6. FIXING IT**\n- Suggested approach (conceptual)\n- Risks to consider\n- How to verify the fix\n- Tests that should be added\n\n**7. UNCERTAINTIES** (if any)\n- What you're still unsure about\n- Edge cases needing more investigation\n\n**OUTPUT**: DIAGNOSTIC_WRITEUP.md\n\n**Quality Check**:\n- Could someone fix this bug confidently from your writeup?\n- Have you proven your case with evidence?\n- Is it clear WHY this is the true source, not just a symptom?\n\n**Mission Complete**: You've tracked down the true source and proven it. Well done.",
-      "agentRole": "You are documenting your successful investigation. You found the truth - now prove it to others.",
-      "requireConfirmation": false
-    }
-  ]
-}
-