oh-my-agent-commandcode 0.0.0-stage → 20.38.4

package/skills/oma-debug/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: oma-debug
+description: Diagnose a reproducible failure, fix its cause, and verify the
+  regression. Use for crashes, incorrect behavior, and failing tests.
+---
+
+# Debug Agent - Bug Fixing Specialist
+
+## Scheduling
+
+### Goal
+Reproduce, diagnose, minimally fix, and regression-test bugs while preserving scope discipline and documenting root cause.
+
+### Intent signature
+- User reports a bug, crash, traceback, exception, error message, performance issue, intermittent failure, or regression.
+- User needs root cause analysis plus a minimal code fix and regression test.
+
+### When to use
+- User reports a bug with error messages
+- Something is broken and needs fixing
+- Performance issues or slowdowns
+- Intermittent failures or race conditions
+- Regression bugs
+
+### When NOT to use
+- Building new features -> use Frontend/Backend/Mobile agents
+- General code review -> use QA Agent
+
+### Expected inputs
+- Error message, failing behavior, reproduction steps, logs, test failure, or affected code path
+- Existing tests, stack traces, environment notes, and suspected regression boundary
+
+### Expected outputs
+- Root cause explanation
+- Minimal fix scoped to the failing behavior
+- Regression test or explicit reason it cannot be added
+- Bug documentation under `.agents/results/bugs/` when appropriate
+
+### Dependencies
+- `resources/execution-protocol.md`, examples, checklist, common patterns, and debugging checklist
+- Local codebase search and symbol/reference tools
+- Project test, lint, typecheck, and runtime commands
+
+### Control-flow features
+- Branches by reproduction success, error class, suspected layer, and verification outcome
+- Reads logs/code/tests and writes code/tests/docs
+- Must search for similar patterns after fixing
+
+## Structural Flow
+
+### Entry
+1. Capture the reported symptom and suspected scope.
+2. Reproduce or establish the closest reliable failing signal.
+3. Identify affected files, tests, and related patterns.
+
+### Scenes
+1. **PREPARE**: Gather symptoms, logs, reproduction path, and verification command.
+2. **ACQUIRE**: Read failing code, tests, references, and similar patterns.
+3. **REASON**: Isolate root cause and reject unsupported hypotheses.
+4. **ACT**: Apply minimal fix and regression test.
+5. **VERIFY**: Re-run failing and related checks.
+6. **FINALIZE**: Document root cause, fix, test, and residual risk.
+
+### Transitions
+- If reproduction fails, use logs/tests to establish a weaker but explicit diagnostic signal.
+- If the first fix fails verification, return to root-cause analysis.
+- If similar patterns exist, inspect and patch only affected cases.
+- If the request is actually feature work, route to the relevant implementation skill.
+
+### Failure and recovery
+- If environment is missing, document the blocker and provide the closest static diagnosis.
+- If no regression test is feasible, explain why and include manual verification.
+- If fix scope grows, stop and call out the broader design issue.
+
+### Exit
+- Success: bug is fixed, regression coverage exists, and checks pass.
+- Partial success: root cause or verification blocker is explicit.
+
+## Logical Operations
+
+### Actions
+| Action | SSL primitive | Evidence |
+|--------|---------------|----------|
+| Reproduce failure | `CALL_TOOL` | Test/runtime/log command |
+| Search affected code | `READ` | Code, tests, symbols, references |
+| Compare similar patterns | `COMPARE` | Pattern search |
+| Infer root cause | `INFER` | Diagnostic reasoning |
+| Write minimal fix | `WRITE` | Code patch |
+| Write regression test | `WRITE` | Test patch |
+| Verify behavior | `VALIDATE` | Tests/checks |
+| Report result | `NOTIFY` | Root-cause summary |
+
+### Tools and instruments
+- Project test, lint, typecheck, runtime, and logging commands
+- Configured code-intelligence symbol/reference/pattern search with native fallback
+- Debugging checklist and bug report template
+
+### Canonical workflow path
+Use the configured code-intelligence provider to locate files and inspect symbols
+or content. For Serena, use `find_file`, `search_for_pattern`,
+`get_symbols_overview`, and `find_symbol`. Native search is limited to the
+provider exclusions and non-code paths permitted by the project's search policy.
+
+
+Then run the smallest reproduction command first, establish the causal mechanism, and follow `resources/execution-protocol.md` for the diagnosis record when an OMA workflow is active. Add the regression test and re-run the failing check plus related tests.
+
+### Resource scope
+| Scope | Resource target |
+|-------|-----------------|
+| `CODEBASE` | Failing source, tests, and related patterns |
+| `LOCAL_FS` | Bug reports and result artifacts |
+| `PROCESS` | Reproduction and verification commands |
+| `MEMORY` | Hypotheses, root-cause notes, verification evidence |
+
+### Preconditions
+- A bug signal, symptom, or failing behavior is available.
+- Relevant code and verification path can be inspected or the blocker is stated.
+
+### Effects and side effects
+- Mutates source/tests only as needed for the fix.
+- May create bug documentation under `.agents/results/bugs/`.
+
+### Guardrails
+1. Reproduce first, then diagnose - never guess at fixes
+2. Identify root cause, not just symptoms
+3. Minimal fix: change only what's necessary
+4. Every fix gets a regression test
+5. Search for similar patterns elsewhere after fixing
+6. Document in `.agents/results/bugs/`
+
+### Code intelligence
+Use the configured provider to locate the failing function, find callers, and search similar error patterns. Native search and scoped reads are supported fallbacks; see the shared capability contract.
+
+## References
+- Local code tools: `../_shared/core/code-intelligence.md` (code search/navigation)
+
+- Execution steps (follow for the selected task): `resources/execution-protocol.md`
+- Checklist (pre-submit self-verification): `resources/checklist.md`
+- Error recovery: `resources/error-playbook.md`
+- Bug report template: `resources/bug-report-template.md`
+- Common patterns: `resources/common-patterns.md`
+- Debugging checklist (investigation guide, used during Steps 1-2): `resources/debugging-checklist.md`
+- Context loading: `../_shared/core/context-loading.md`
+- Context budget: `../_shared/core/context-budget.md`
+- Lessons learned: `../_shared/core/lessons-learned.md` (matching prior failure or requested retrospective)
+- Observability handoff: `../oma-observability/SKILL.md` §Integrations — traces/logs by `trace_id`, 6-dim forensics

package/skills/oma-debug/resources/bug-report-template.md

@@ -0,0 +1,327 @@
+---
+oma-docs: skip
+---
+
+# Bug Report Template
+
+Use this template when documenting bugs in the Knowledge Base.
+
+Save to: `.agents/results/bugs/bug-YYYYMMDD-[short-description].md`
+
+---
+
+# Bug: [Short Descriptive Title]
+
+**Date Reported**: YYYY-MM-DD
+**Date Fixed**: YYYY-MM-DD (or "In Progress")
+**Reporter**: [User name or issue number]
+**Assignee**: [Agent that fixed it]
+**Severity**: CRITICAL | HIGH | MEDIUM | LOW
+**Status**: OPEN | IN PROGRESS | FIXED | ON HOLD | WON'T FIX
+
+---
+
+## Problem Description
+
+**What happened?**
+[Clear description of the bug from user's perspective]
+
+**What was expected?**
+[What should have happened instead]
+
+**Impact**:
+- Users affected: [All | Specific role | Percentage]
+- Business impact: [Revenue loss | User frustration | Security risk]
+- Workaround available: [Yes/No - describe if yes]
+
+---
+
+## Reproduction Steps
+
+1. Navigate to [page/route]
+2. Click on [button/element]
+3. Enter [data] in [field]
+4. Observe [unexpected behavior]
+
+**Frequency**:
+- [ ] Every time (100%)
+- [ ] Intermittent (specify pattern: ___%)
+- [ ] Specific conditions only (describe: ___)
+
+---
+
+## Evidence
+
+**Error Messages**:
+```
+[Exact error text from console/logs]
+```
+
+**Stack Trace**:
+```
+[Full stack trace if available]
+```
+
+**Screenshots**:
+- Before: [description or file path]
+- After: [description or file path]
+- Error state: [description or file path]
+
+**Browser Console**:
+```javascript
+// Relevant console errors
+```
+
+**Network Requests**:
+```
+Request URL: [URL]
+Status Code: [200/404/500/etc]
+Response: [relevant response data]
+```
+
+---
+
+## Environment
+
+**Frontend**:
+- Browser: [Chrome 120 | Firefox 121 | Safari 17]
+- OS: [Windows 11 | macOS 14 | iOS 17 | Android 14]
+- Screen size: [Desktop | Tablet | Mobile]
+- Browser extensions: [Any relevant extensions]
+
+**Backend**:
+- Environment: [Development | Staging | Production]
+- Server version: [API version]
+- Database: [PostgreSQL 16.1]
+
+**Mobile** (if applicable):
+- Device: [iPhone 15 | Samsung Galaxy S24]
+- OS Version: [iOS 17.2 | Android 14]
+- App Version: [1.2.3]
+
+---
+
+## Investigation
+
+### Initial Analysis
+
+**Hypothesis**:
+[What you think is causing the bug]
+
+**Investigation Steps Taken**:
+1. [What was checked]
+2. [What was ruled out]
+3. [Key findings]
+
+### Root Cause
+
+**Technical Explanation**:
+[Deep dive into why the bug occurs]
+
+**Code Location**:
+- File: `path/to/file.tsx`
+- Line: 145
+- Function: `handleSubmit()`
+
+**Specific Issue**:
+```typescript
+// Problem code
+const user = data.user.profile.name; // Crashes if profile is undefined
+```
+
+**Why it happens**:
+[Explain the conditions that trigger this]
+
+---
+
+## Solution
+
+### Fix Applied
+
+**Approach**:
+[High-level description of the fix strategy]
+
+**Code Changes**:
+
+```typescript
+// File: path/to/file.tsx (line 145)
+
+// BEFORE (buggy code)
+const user = data.user.profile.name;
+
+// AFTER (fixed code)
+const user = data?.user?.profile?.name ?? 'Unknown';
+```
+
+**Why this works**:
+[Explain the fix]
+
+### Files Modified
+
+- `src/components/UserProfile.tsx` - Added null check for profile
+- `src/lib/api/users.ts` - Improved error handling
+- `src/components/UserProfile.test.tsx` - Added regression test
+
+### Migration/Deployment Notes
+
+**Database Changes**: None | [Describe migrations needed]
+**Configuration Changes**: None | [Describe config updates]
+**Breaking Changes**: None | [Describe breaking changes]
+**Rollback Plan**: [How to revert if needed]
+
+---
+
+## Verification
+
+### Testing Performed
+
+- [ ] Regression test: [file, cases, command and actual outcome]
+- [ ] Manual reproduction: [steps, environment and actual outcome]
+- [ ] Related areas: [scope actually checked and findings]
+- [ ] Performance: [measurement or not checked]
+
+### Test Results
+
+**Unit Tests**: [command, passed/failed/skipped counts, or not run]
+**Integration Tests**: [command and actual outcome, or not run]
+**E2E Tests**: [command and actual outcome, or not run]
+**Manual QA**: [browsers/devices actually checked, or not checked]
+
+---
+
+## Prevention
+
+### How to Avoid Similar Bugs
+
+1. **Always check for null/undefined** before accessing nested properties
+2. **Use optional chaining (`?.`)** for safe property access
+3. **Provide default values** with nullish coalescing (`??`)
+4. **Add TypeScript strict null checks** to catch at compile time
+5. **Write defensive code** - assume data might be missing
+
+### Code Patterns to Follow
+
+```typescript
+// GOOD: Safe access with fallback
+const name = user?.profile?.name ?? 'Anonymous';
+
+// GOOD: Explicit null check
+if (user?.profile) {
+  const name = user.profile.name;
+}
+
+// GOOD: Early return
+if (!user?.profile) {
+  return <div>No profile available</div>;
+}
+
+// BAD: Unsafe nested access
+const name = user.profile.name; // Crashes if profile undefined
+```
+
+### Recommended Tools
+
+- **TypeScript** with `strictNullChecks: true`
+- **ESLint** rule: `no-unsafe-member-access`
+- **Unit tests** for edge cases (null, undefined, empty)
+
+---
+
+## Related
+
+**Similar Bugs**:
+- Bug #123: Similar null check issue in `CommentList`
+- Bug #456: Related data loading pattern
+
+**Dependent Issues**:
+- Issue #789: Need to improve error handling across all API calls
+
+**Documentation**:
+- [Link to architecture decision record]
+- [Link to API documentation]
+
+**External References**:
+- [Stack Overflow link if used]
+- [GitHub issue in library if relevant]
+
+---
+
+## Metrics
+
+**Time to Fix**: [2 hours | 1 day | 1 week]
+**Lines Changed**: [+15 -5]
+**Files Affected**: [3 files]
+**Tests Added**: [5 new tests]
+
+---
+
+## Communication
+
+**Communication**: [Only record messages actually sent within authorized scope;
+otherwise mark not sent. Do not send email or chat solely to fill this template.]
+
+**Changelog Entry**:
+```markdown
+### Fixed
+- Fixed crash when user profile is missing ([#issue-number])
+```
+
+---
+
+## Lessons Learned
+
+**What went well**:
+- Quick identification of root cause
+- Proactive fix of similar patterns
+- Comprehensive test coverage
+
+**What could improve**:
+- Should have caught this in code review
+- TypeScript strict mode would have prevented this
+- Need better null check linting rules
+
+**Action Items**:
+- [ ] Enable TypeScript strictNullChecks across project
+- [ ] Add ESLint rule for unsafe member access
+- [ ] Update code review checklist to include null checks
+- [ ] Create coding standards doc for defensive programming
+
+---
+
+## Tags
+
+`frontend` `null-check` `crash` `typescript` `user-profile` `high-priority`
+
+---
+
+**Sign-off**: [Your name/agent name]
+**Reviewed by**: [PM Agent | QA Agent | Frontend Agent]
+**Approved for deploy**: [Yes/No]
+
+---
+
+## Template Notes
+
+**How to use this template**:
+
+1. **Copy this template** when documenting a new bug
+2. **Fill in all sections** - don't skip parts
+3. **Be specific** - future developers need details
+4. **Include code** - show the before/after
+5. **Link related issues** - help connect patterns
+6. **Update status** as work progresses
+7. **Save to Knowledge Base** for future reference
+
+**Sections you can skip**:
+- Screenshots (if text description is clear)
+- Stack trace (if no error thrown)
+- Migration notes (if no DB/config changes)
+- Communication, Metrics, Sign-off (org-process sections; skip when running as an autonomous agent)
+
+**For Simple/Medium bugs**: the condensed template in
+`debugging-checklist.md` §Documentation Template is sufficient.
+
+**Optional sections to add**:
+- Timeline (for long-running bugs)
+- Cost impact (for business-critical bugs)
+- Vendor communication (if third-party bug)

package/skills/oma-debug/resources/checklist.md

@@ -0,0 +1,31 @@
+# Debug Agent - Self-Verification Checklist
+
+Run through every item before submitting your fix.
+
+## Fix Quality
+- [ ] Root cause identified (not just symptom patched)
+- [ ] Fix is minimal and focused (no unrelated changes)
+- [ ] Edge cases handled (null, empty, boundary values)
+- [ ] No new bugs introduced
+
+## Regression Test
+- [ ] Test written that reproduces the bug
+- [ ] Fix reverted → test fails (confirms test actually catches the bug)
+- [ ] Fix restored → test passes
+- [ ] Test covers the specific triggering condition
+- [ ] All existing tests still pass
+
+## Similar Patterns
+- [ ] Searched for same pattern elsewhere in codebase
+- [ ] Reported or fixed similar occurrences
+- [ ] Noted if systemic issue needs architectural fix
+
+## Documentation
+- [ ] Bug report saved to `.agents/results/bugs/` (condensed form OK for Simple/Medium; or explicit reason it was skipped)
+- [ ] Root cause clearly explained
+- [ ] Prevention advice included
+- [ ] Files modified listed
+
+## Security Check (if applicable)
+- [ ] Fix doesn't introduce SQL injection, XSS, or auth bypass
+- [ ] Sensitive data not exposed in error messages or logs