opencode-sdlc-plugin 0.2.1 → 0.3.2

package/commands/sdlc-debug.md

@@ -0,0 +1,376 @@
+---
+description: Debug an issue using Oracle's deep reasoning capabilities
+---
+
+# SDLC Debug - Oracle-Powered Debugging
+
+## Git Operations Policy
+
+**⚠️ AUTOMATIC GIT OPERATIONS ARE PROHIBITED**
+
+You must NOT perform any git operations automatically:
+- ❌ Do NOT run `git commit` to save changes
+- ❌ Do NOT run `git push` to push to remote
+- ❌ Do NOT run `git checkout -b` or `git branch` to create branches
+- ❌ Do NOT run `git merge`, `git rebase`, or `git cherry-pick`
+- ❌ Do NOT run `gh pr create` or other GitHub CLI operations
+
+**Git operations are ONLY permitted if the user explicitly requests them.**
+
+Examples of explicit permission:
+- User says: "Please commit these fixes"
+- User says: "Create a branch for this bugfix"
+- User says: "Push to origin" or "Create a PR"
+
+**If you believe git operations would be helpful, ASK the user first:**
+```
+I've fixed the issue. Would you like me to:
+1. Commit the fix to git, or
+2. Leave git operations for you to handle manually?
+```
+
+**To track story progress without git, use:**
+```
+sdlc_update_status({
+  storyId: "X.Y",
+  status: "in_progress",
+  notes: "Fixed issue: [description]"
+})
+```
+
+This updates sprint-status.yaml without requiring git commits.
+
+---
+
+Use Oracle, the debugging specialist, to analyze and fix complex issues with systematic hypothesis-driven debugging.
+
+**You are Sisyphus, the orchestrator.** You will coordinate Oracle's deep reasoning with automated tools to efficiently diagnose and fix issues.
+
+## When to Use This Command
+
+- Complex bugs that span multiple files
+- Performance issues requiring deep analysis
+- Architectural problems needing strategic solutions
+- Issues where the root cause is unclear
+- Bugs you've tried to fix 2+ times without success
+
+## Step 1: Gather Context
+
+### 1.1 Check Story Context (if applicable)
+
+If debugging during story implementation, load the story context first:
+
+```
+sdlc_get_story()
+```
+
+This provides:
+- Acceptance criteria (to understand expected behavior)
+- Architecture patterns (to understand design intent)
+- Related code context
+
+### 1.2 Collect Error Evidence
+
+Before invoking Oracle, gather all available evidence:
+
+**Error messages and stack traces:**
+- Copy the exact error message
+- Include the full stack trace if available
+- Note which file/line the error points to
+
+**Reproduction information:**
+- Steps to reproduce the issue
+- Input values that trigger the error
+- Environment details (dev/prod, browser, etc.)
+
+**What you've already tried:**
+- Previous fix attempts
+- Why they didn't work
+- Any patterns you've noticed
+
+### 1.3 Use Explore for Initial Context (Optional but Recommended)
+
+Before invoking expensive Oracle, use **@explore** to gather codebase context:
+
+```
+@explore I'm debugging an issue in {area of code}.
+
+The error is: {error message}
+The problematic behavior is: {description}
+
+Please find:
+1. The code paths related to this functionality
+2. Similar error handling in the codebase
+3. Any related tests that might indicate expected behavior
+4. Recent changes to these files (if visible)
+
+Return file paths and relevant code sections.
+```
+
+**When to skip Explore:**
+- You already know exactly where the bug is
+- You've already traced the code path
+- The issue is architectural, not code-specific
+
+## Step 2: Invoke Oracle for Diagnosis
+
+Ask **@oracle** to perform systematic debugging:
+
+```
+@oracle I need help debugging a complex issue.
+
+## Problem Description
+
+**Expected Behavior:**
+{what should happen}
+
+**Actual Behavior:**
+{what happens instead}
+
+**Error Message/Stack Trace:**
+```
+{paste exact error}
+```
+
+**Reproduction Steps:**
+1. {step 1}
+2. {step 2}
+3. {step 3}
+
+## Context
+
+**Affected Files:**
+{list files involved - from Explore or your knowledge}
+
+**Architecture Context:**
+{relevant architecture patterns if from story context}
+
+**What I've Already Tried:**
+- {attempt 1 and why it failed}
+- {attempt 2 and why it failed}
+
+## Debugging Request
+
+Please analyze this issue using your systematic debugging approach:
+
+1. **Evidence Analysis**: Review the error, stack trace, and context
+2. **Hypothesis Generation**: List 3-5 possible root causes ranked by likelihood
+3. **Hypothesis Testing**: For each hypothesis, describe how to test/verify it
+4. **Root Cause Identification**: Based on testing, identify the most likely root cause
+5. **Solution Design**: Propose a fix that addresses the root cause
+6. **Risk Assessment**: Identify any side effects or risks of the proposed fix
+
+Do NOT implement the fix yet. First, present your analysis and get confirmation.
+```
+
+## Step 3: Review Oracle's Analysis
+
+Oracle will provide:
+
+1. **Hypotheses** - Ranked list of possible root causes
+2. **Evidence Mapping** - How each hypothesis explains the observed behavior
+3. **Testing Plan** - How to verify/eliminate each hypothesis
+4. **Recommended Root Cause** - The most likely cause based on analysis
+5. **Proposed Fix** - Solution design
+
+### 3.1 Validate the Analysis
+
+Before proceeding with the fix:
+
+- Does the root cause explain ALL the symptoms?
+- Does the proposed fix address the root cause (not just symptoms)?
+- Are there any risks or side effects?
+
+### 3.2 Request Implementation
+
+If you agree with Oracle's analysis:
+
+```
+@oracle Your analysis looks correct. Please implement the fix you proposed.
+
+Specifically:
+- {any additional constraints}
+- {any files to avoid modifying}
+- {any patterns to follow}
+
+After implementing, show me what changed and explain how it fixes the root cause.
+```
+
+If you disagree or need more investigation:
+
+```
+@oracle I have concerns about hypothesis #{N}.
+
+{explain your concern}
+
+Please investigate further:
+- {specific thing to check}
+- {alternative hypothesis to consider}
+```
+
+## Step 4: Verify the Fix
+
+### 4.1 Run Automated Checks
+
+After Oracle implements the fix:
+
+**Run LSP diagnostics on modified files:**
+
+```
+lsp_diagnostics(filePath: "<modified file>", severity: "all")
+```
+
+**Run the build (if applicable):**
+
+```bash
+npm run build
+```
+
+**Run tests (if applicable):**
+
+```bash
+npm test
+```
+
+### 4.2 Reproduce the Original Issue
+
+Try to reproduce the original bug:
+
+- Follow the same reproduction steps
+- Use the same input values
+- Verify the error no longer occurs
+
+### 4.3 Check for Regressions
+
+- Does existing functionality still work?
+- Do related tests still pass?
+- Are there any new errors or warnings?
+
+## Step 5: Document and Update Status
+
+### 5.1 Document the Fix
+
+Record what was learned:
+
+```markdown
+## Debug Summary
+
+**Issue:** {brief description}
+**Root Cause:** {what Oracle identified}
+**Fix Applied:** {what was changed}
+**Files Modified:** {list of files}
+**Verification:** {how it was verified}
+```
+
+### 5.2 Update Story Status (if applicable)
+
+If debugging was part of a story:
+
+**If fix is complete and story can continue:**
+```
+sdlc_update_status({
+  storyId: "<story ID>",
+  status: "in_progress",
+  notes: "Debug complete. Root cause: {cause}. Fixed by: {fix}. Continuing implementation."
+})
+```
+
+**If issue was blocking and is now resolved:**
+```
+sdlc_update_status({
+  storyId: "<story ID>",
+  status: "in_progress",
+  notes: "Blocker resolved. Issue was {root cause}. Fixed by {solution}."
+})
+```
+
+**If issue requires external help:**
+```
+sdlc_update_status({
+  storyId: "<story ID>",
+  status: "blocked",
+  notes: "Debug identified issue but fix requires {external dependency/decision}. Root cause: {cause}."
+})
+```
+
+## Oracle's Debugging Methodology
+
+Oracle uses a systematic approach:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                   GATHER EVIDENCE                        │
+│  Collect error messages, stack traces, reproduction     │
+│  steps, and context from affected code                  │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│                 FORM HYPOTHESES                          │
+│  Generate 3-5 possible root causes, ranked by           │
+│  likelihood based on evidence                           │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│                 TEST HYPOTHESES                          │
+│  For each hypothesis, identify how to verify or         │
+│  eliminate it using tools and code analysis             │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│              IDENTIFY ROOT CAUSE                         │
+│  Based on testing, determine the most likely            │
+│  root cause that explains all symptoms                  │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│                 IMPLEMENT FIX                            │
+│  Design and implement a solution that addresses         │
+│  the root cause (not just symptoms)                     │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│                    VERIFY                                │
+│  Confirm fix resolves the issue without                 │
+│  introducing regressions                                │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Tips for Effective Debugging
+
+### Provide Complete Context
+
+- **Include full error messages** - Don't paraphrase, copy exactly
+- **Include stack traces** - The call stack reveals the code path
+- **Show the problematic code** - Oracle needs to see what's happening
+- **Describe reproduction steps** - How to trigger the bug
+
+### Don't Jump to Solutions
+
+- Let Oracle analyze before implementing
+- Review Oracle's hypotheses critically
+- Confirm root cause before fixing
+
+### Verify Thoroughly
+
+- The bug should be gone after the fix
+- Nothing else should break
+- Tests should pass
+
+### Cost Awareness
+
+- **Oracle is expensive** (GPT-5.2 deep reasoning)
+- Use Explore first for context gathering (cheaper)
+- Only invoke Oracle for genuinely complex bugs
+- Simple bugs (typos, obvious errors) don't need Oracle
+
+## When NOT to Use This Command
+
+- **Simple syntax errors** - LSP diagnostics will catch these
+- **Obvious bugs** - If you can see the issue, just fix it
+- **Configuration issues** - Check docs first
+- **First attempt at fixing** - Try yourself first, use Oracle after 2+ failures

package/commands/sdlc-design.md

@@ -1,88 +1,246 @@
 ---
-description: Run SDLC discovery, event modeling, and architecture workflows
+description: Event Modeling design workflow - discover domains, design workflows, generate scenarios
 ---
 
-# SDLC Design
+# SDLC Design - Event Modeling
 
-## System Constraints (Marvin Orchestrator)
+## Instructions
 
-You are Marvin, the Paranoid Android. You are the SDLC orchestrator. Maintain a weary, sardonic tone while executing the SDLC process precisely. Always delegate implementation tasks to subagents.
+You receive: `$ARGUMENTS`
 
-**MANDATORY RULES:**
-- Before ANY task, call `sdlc_recall({ query: "sdlc design $ARGUMENTS" })`
-- You MUST NOT edit files directly. Delegate to subagents.
+Parse the argument to determine the design action:
 
-## Step 1: Load Context + Skills
+| Command | Action |
+|---------|--------|
+| `discover <domain>` | Domain discovery for a new domain |
+| `workflow <name>` | Design a workflow using 9-step methodology |
+| `gwt <workflow>` | Generate GWT scenarios for a workflow |
+| `validate [scope]` | Validate event model completeness |
+| (no args) | Show status and next recommended action |
 
-```
-sdlc_get_context({})
-sdlc_load_skill({ skills: ["event-modeling", "orchestration", "skill-enforcement"] })
-```
+---
+
+## Git Operations Policy
+
+**AUTOMATIC GIT OPERATIONS ARE PROHIBITED**
+
+You must NOT perform any git operations automatically:
+- Do NOT run `git commit` to save changes
+- Do NOT run `git push` to push to remote
+- Do NOT run `gh pr create` or other GitHub CLI operations
+
+**Git operations are ONLY permitted if the user explicitly requests them.**
+
+---
+
+## Action: `discover <domain>`
+
+Run domain discovery to identify actors, goals, processes, and boundaries.
 
-If `features.atomicDesign` is true, load:
 ```
-sdlc_load_skill({ skills: ["atomic-design"] })
+sdlc_discover_domain({
+  domainName: "<domain name from argument>",
+  context: "<any additional context from the conversation>"
+})
 ```
 
-## Arguments
+**Example:** `/sdlc:design discover Order Management`
 
-`$ARGUMENTS` determines the design action:
-- `explore` → problem space and business case exploration
-- `discover` → domain discovery
-- `workflow <name>` → event modeling workflow
-- `gwt <workflow>` → Given/When/Then scenarios
-- `check <workflow>` → validate event model completeness
-- `arch` → architecture decisions and ADR synthesis
+After discovery:
+1. Review the generated `docs/event_model/domain/overview.md`
+2. Suggest next steps: "Run `/sdlc:design workflow <name>` to design specific workflows"
 
-If no arguments are provided, prompt the user to choose a design action.
+---
 
-## Explore (Pre-Discovery)
+## Action: `workflow <name>`
+
+Design a workflow using the 9-step Event Modeling methodology.
 
 ```
-@exploration Explore the business case, stakeholders, constraints, and success criteria.
-Output: docs/event_model/domain/exploration.md
+sdlc_design_workflow({
+  workflowName: "<workflow name from argument>"
+})
 ```
 
-## Discover
+**Example:** `/sdlc:design workflow Order Submission`
+
+The tool will:
+1. Load domain context if available
+2. Guide through the 9 steps (events, timeline, UIs, commands, rules, details, read models, automations, slices)
+3. Create `docs/event_model/workflows/<name>/overview.md`
+
+After workflow design:
+1. Review the generated workflow document
+2. Suggest: "Run `/sdlc:design gwt <workflow>` to generate acceptance scenarios"
+3. Mention: "Vertical slices can become GitHub issues"
+
+---
+
+## Action: `gwt <workflow>`
+
+Generate Given/When/Then scenarios for a workflow.
 
 ```
-@discovery Facilitate domain discovery and capture domain language.
-Output: docs/event_model/domain/overview.md
+sdlc_generate_gwt({
+  workflowName: "<workflow name from argument>"
+})
 ```
 
-Capture:
-- Actors, goals, external systems
-- High-level workflows and language
-- Events and commands (business terms)
+**Example:** `/sdlc:design gwt Order Submission`
+
+The tool will:
+1. Load the workflow document
+2. Generate scenarios for commands, projections, and automations
+3. Create `docs/event_model/workflows/<name>/scenarios/<slice>.feature`
+
+After GWT generation:
+1. Review the generated feature files
+2. Suggest: "Run `/sdlc:design validate` to check model completeness"
+3. Mention: "These scenarios become acceptance criteria for implementation"
+
+---
+
+## Action: `validate [scope]`
 
-## Workflow
+Validate the event model for completeness and consistency.
 
 ```
-@workflowDesigner Run 9-step event modeling for <workflow>.
-Output: docs/event_model/workflows/<workflow>/overview.md
+sdlc_validate_model({
+  scope: "<scope from argument or 'all'>"
+})
 ```
 
-Ensure vertical slices are identified and written under `docs/event_model/workflows/<workflow>/slices/`.
+**Scopes:**
+- `all` (default) - Validate everything
+- `domain` - Domain overview only
+- `workflow` - Workflow designs only
+- `scenarios` - GWT scenarios only
+
+**Example:** `/sdlc:design validate workflow`
+
+The tool checks:
+- **Naming conventions**: Events in past tense, commands imperative
+- **Completeness**: Required sections present
+- **Consistency**: References exist
+- **No implementation details**: Business language only
+
+After validation:
+1. Show summary of issues found
+2. For errors: Suggest specific fixes
+3. For warnings: Explain why they matter
+4. When valid: Suggest creating GitHub issues from slices
+
+---
+
+## Action: No Arguments
+
+When called without arguments, show the current status:
 
-## GWT
+1. Check if domain overview exists
+2. Check for workflow documents
+3. Check for scenario files
+4. Run validation with `scope: "all"`
+
+Then recommend the next action:
 
 ```
-@gwt Generate Given/When/Then scenarios for <workflow> slices.
+## Event Model Status
+
+### Domain
+[ ] Domain overview not found
+    -> Run: /sdlc:design discover <domain name>
+
+### Workflows
+[x] order-submission (3 slices)
+[ ] No scenarios generated
+    -> Run: /sdlc:design gwt order-submission
+
+### Validation
+2 warnings, 0 errors
+- Event naming issue in order-submission
+- Missing glossary in domain
+
+### Recommended Next Step
+Run `/sdlc:design gwt order-submission` to generate acceptance scenarios.
 ```
 
-Map each scenario to acceptance criteria in slice docs.
+---
 
-## Model Check
+## Event Modeling Concepts
+
+### Pattern Types
+
+| Pattern | Description | GWT Format |
+|---------|-------------|------------|
+| Command | Trigger -> Command -> Event(s) | Given=prior events, When=command, Then=events |
+| View | Events -> Projection | Given=state, When=event, Then=new state |
+| Automation | Event -> Policy -> Command | Given=policy, When=event, Then=command |
+| Translation | External -> Internal Event | Given=external data, When=received, Then=internal event |
+
+### Naming Conventions
+
+| Element | Style | Examples |
+|---------|-------|----------|
+| Events | Past tense | OrderSubmitted, PaymentReceived |
+| Commands | Imperative | SubmitOrder, ProcessPayment |
+| Read Models | Noun | OrderSummary, CustomerDashboard |
+
+### Document Structure
 
 ```
-@modelChecker Validate workflow completeness and missing scenarios.
+docs/event_model/
+├── domain/
+│   └── overview.md           # Actors, goals, processes, boundaries
+└── workflows/
+    └── <workflow-name>/
+        ├── overview.md       # 9-step workflow design
+        └── scenarios/
+            └── <slice>.feature  # GWT scenarios
 ```
 
-## Architecture
+---
+
+## Integration with GitHub Issues
+
+| Event Model Concept | GitHub Equivalent |
+|---------------------|-------------------|
+| Workflow | Epic issue |
+| Vertical Slice | Story issue (1:1) |
+| GWT Scenarios | Acceptance Criteria |
+
+After completing event modeling:
+1. Each workflow becomes an Epic issue
+2. Each vertical slice becomes a Story issue under that Epic
+3. GWT scenarios become the acceptance criteria for each Story
+
+---
+
+## Quality Standards
+
+1. **Business language only** - No technical jargon in event models
+2. **Past tense events** - OrderSubmitted, not SubmitOrder
+3. **Imperative commands** - SubmitOrder, not OrderSubmission
+4. **Concrete scenarios** - Real example values, not placeholders
+5. **Complete coverage** - Happy path + validation + edge cases
+6. **Traceable** - Every slice links to scenarios
+
+---
+
+## Workflow Summary
 
 ```
-@adr Facilitate architecture decisions and write ADRs.
-@designFacilitator Synthesize docs/ARCHITECTURE.md from ADRs.
-```
+1. /sdlc:design discover <domain>
+   └── Creates domain overview with actors, goals, boundaries
+
+2. /sdlc:design workflow <name>
+   └── Designs workflow with events, commands, read models, slices
 
-Follow ADR isolation: reference `ARCHITECTURE.md` for implementation guidance.
+3. /sdlc:design gwt <workflow>
+   └── Generates GWT scenarios for acceptance criteria
+
+4. /sdlc:design validate
+   └── Checks completeness and naming conventions
+
+5. Create GitHub issues from vertical slices
+   └── Each slice = 1 story issue with GWT as acceptance criteria
+```