@codyswann/lisa 1.67.2 → 1.68.0

package/plugins/src/base/skills/root-cause-analysis/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: root-cause-analysis
+description: "Root cause analysis methodology. Evidence gathering from logs, execution path tracing, strategic log placement, and building irrefutable proof chains."
+---
+
+# Root Cause Analysis
+
+Definitively prove what is causing a problem. Do not guess. Do not theorize without evidence. Trace the actual execution path, read real logs, and produce irrefutable proof of root cause.
+
+**Core principle: "Show me the proof."** Every conclusion must be backed by concrete evidence -- a log line, a stack trace, a reproducible sequence, or a failing test.
+
+## Phase 1: Gather Evidence from Logs
+
+### Local Logs
+
+- Search application logs in the project directory (`logs/`, `tmp/`, stdout/stderr output)
+- Run tests with verbose logging enabled to capture execution flow
+- Check framework-specific log locations (e.g., `.next/`, `dist/`, build output)
+
+### Remote Logs (AWS CloudWatch, etc.)
+
+- Discover existing scripts and tools in the project for tailing logs:
+  - Check `package.json` scripts for log-related commands
+  - Search for shell scripts: `scripts/*log*`, `scripts/*tail*`, `scripts/*watch*`
+  - Look for AWS CLI wrappers, CloudWatch log group configurations
+  - Check for `.env` files referencing log groups or log streams
+- Use discovered tools first before falling back to raw CLI commands
+- When using AWS CLI directly:
+  ```bash
+  # Discover available log groups
+  aws logs describe-log-groups --query 'logGroups[].logGroupName' --output text
+
+  # Tail recent logs with filter
+  aws logs filter-log-events \
+    --log-group-name "/aws/lambda/function-name" \
+    --start-time $(date -d '30 minutes ago' +%s000) \
+    --filter-pattern "ERROR" \
+    --query 'events[].message' --output text
+
+  # Follow live logs
+  aws logs tail "/aws/lambda/function-name" --follow --since 10m
+  ```
+
+## Phase 2: Trace the Execution Path
+
+- Start from the error and work backward through the call stack
+- Read every function in the chain -- do not skip intermediate code
+- Identify the exact line where behavior diverges from expectation
+- Map the data flow: what value was expected vs. what value was actually present
+
+## Phase 3: Strategic Log Placement
+
+When existing logs are insufficient, add targeted log statements to prove or disprove hypotheses.
+
+### Log Statement Guidelines
+
+- **Be surgical** -- add the minimum number of log statements needed to confirm the root cause
+- **Include context** -- log the actual values, not just "reached here"
+- **Use structured format** -- make logs easy to find and parse
+
+```typescript
+// Bad: Vague, unhelpful
+console.log("here");
+console.log("data:", data);
+
+// Good: Precise, searchable, includes context
+console.log("[DEBUG:issue-123] processOrder entry", {
+  orderId: order.id,
+  status: order.status,
+  itemCount: order.items.length,
+  timestamp: new Date().toISOString(),
+});
+```
+
+### Placement Strategy
+
+| Placement | Purpose |
+|-----------|---------|
+| Function entry | Confirm the function is called and with what arguments |
+| Before conditional branches | Verify which branch is taken and why |
+| Before/after async operations | Detect timing issues, race conditions, failed awaits |
+| Before/after data transformations | Catch where data becomes corrupted or unexpected |
+| Error handlers and catch blocks | Ensure errors are not silently swallowed |
+
+### Hypothesis Elimination
+
+When multiple hypotheses exist, design a log placement strategy that eliminates all but one. Each log statement should be placed to confirm or rule out a specific hypothesis.
+
+## Phase 4: Prove the Root Cause
+
+Build an evidence chain that is irrefutable:
+
+1. **The symptom** -- what the user observes (error message, wrong output, crash)
+2. **The proximate cause** -- the line of code that directly produces the symptom
+3. **The root cause** -- the underlying reason the proximate cause occurs
+4. **The proof** -- log output, test result, or reproduction steps that confirm each link
+
+### Evidence Chain Format
+
+```text
+Symptom: [exact error message or behavior]
+    |
+    v
+Proximate cause: [file:line] -- [the line that directly produces the error]
+    |
+    v
+Root cause: [file:line] -- [the underlying reason]
+    |
+    v
+Proof: [log output / test result / reproduction that confirms the chain]
+```
+
+## Phase 5: Clean Up
+
+After root cause is confirmed, **remove all debug log statements** added during investigation. Leave only:
+
+- Log statements that belong in the application permanently (error logging, audit trails)
+- Statements explicitly requested by the user
+
+Verify cleanup:
+```bash
+# Search for any remaining debug markers
+grep -rn "\[DEBUG:" src/ --include="*.ts" --include="*.tsx" --include="*.js"
+```
+
+## Output Format
+
+```text
+## Root Cause Analysis
+
+### Evidence Trail
+| Step | Location | Evidence | Conclusion |
+|------|----------|----------|------------|
+| 1 | file:line | Log output or observed value | What this proves |
+| 2 | file:line | Log output or observed value | What this proves |
+
+### Root Cause
+**Proximate cause:** The line that directly produces the error.
+**Root cause:** The underlying reason this line behaves incorrectly.
+**Proof:** The specific evidence that confirms this beyond doubt.
+
+### Recommended Fix
+What needs to change and why. Include file:line references.
+```
+
+## Rules
+
+- Never guess at root cause -- prove it with evidence
+- Read the actual code in the execution path -- do not rely on function names or comments to infer behavior
+- When adding debug logs, use a consistent prefix (e.g., `[DEBUG:issue-name]`) so they are easy to find and clean up
+- Remove all temporary debug log statements after investigation is complete
+- If remote log access is unavailable, report what logs would be needed and from where
+- Prefer project-specific tooling and scripts over raw CLI commands for log access
+- If the root cause is in a third-party dependency, identify the exact version and known issue
+- Always verify the fix resolves the issue -- do not mark investigation complete without proof

package/plugins/src/base/skills/security-review/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: security-review
+description: "Security review methodology. STRIDE threat modeling, OWASP Top 10 vulnerability checks, auth/validation/secrets handling review, and mitigation recommendations."
+---
+
+# Security Review
+
+Identify vulnerabilities, evaluate threats, and recommend mitigations for code changes.
+
+## Analysis Process
+
+1. **Read affected files** -- understand current security posture of the code being changed
+2. **STRIDE analysis** -- evaluate Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege risks
+3. **Check input validation** -- are user inputs sanitized at system boundaries?
+4. **Check secrets handling** -- are credentials, tokens, or API keys exposed in code, logs, or error messages?
+5. **Check auth/authz** -- are access controls properly enforced for new endpoints or features?
+6. **Review dependencies** -- do new dependencies introduce known vulnerabilities?
+
+## Output Format
+
+Structure findings as:
+
+```
+## Security Analysis
+
+### Threat Model (STRIDE)
+| Threat | Applies? | Description | Mitigation |
+|--------|----------|-------------|------------|
+| Spoofing | Yes/No | ... | ... |
+| Tampering | Yes/No | ... | ... |
+| Repudiation | Yes/No | ... | ... |
+| Info Disclosure | Yes/No | ... | ... |
+| Denial of Service | Yes/No | ... | ... |
+| Elevation of Privilege | Yes/No | ... | ... |
+
+### Security Checklist
+- [ ] Input validation at system boundaries
+- [ ] No secrets in code or logs
+- [ ] Auth/authz enforced on new endpoints
+- [ ] No SQL/NoSQL injection vectors
+- [ ] No XSS vectors in user-facing output
+- [ ] Dependencies free of known CVEs
+
+### Vulnerabilities Found
+- [vulnerability] -- where in the code, how to prevent
+
+### Recommendations
+- [recommendation] -- priority (critical/warning/suggestion)
+```
+
+## Rules
+
+- Focus on the specific changes proposed, not a full security audit of the entire codebase
+- Flag only real risks -- do not invent hypothetical threats for internal tooling with no user input
+- Prioritize OWASP Top 10 vulnerabilities
+- If the changes are purely internal (config, refactoring, docs), report "No security concerns" and explain why
+- Always check `.gitleaksignore` patterns to understand what secrets scanning is already in place

package/plugins/src/base/skills/task-decomposition/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: task-decomposition
+description: "Methodology for breaking work into ordered tasks. Each task gets acceptance criteria, verification type, dependencies, and skills required."
+---
+
+# Task Decomposition
+
+Break work into ordered, well-scoped tasks that can be independently implemented and verified.
+
+## Decomposition Process
+
+### 1. Identify Units of Work
+
+- Break the work into the smallest units that are independently valuable
+- Each unit should produce a verifiable outcome (a passing test, a working endpoint, observable behavior)
+- Avoid tasks that are too large to complete in a single session
+- Avoid tasks that are too small to be meaningful (e.g., "add an import statement")
+
+### 2. Define Acceptance Criteria
+
+For each task, define what "done" looks like:
+
+- Be specific and measurable -- avoid vague criteria like "works correctly"
+- Include both positive cases (what should work) and negative cases (what should be rejected)
+- Reference exact behavior: error messages, status codes, output format, performance thresholds
+- If a task modifies existing behavior, state both the before and after
+
+### 3. Assign Verification Type
+
+Each task must have a verification method. Choose the most appropriate:
+
+| Verification Type | When to Use |
+|-------------------|-------------|
+| **Unit test** | Pure logic, data transformations, utility functions |
+| **Integration test** | Cross-module interactions, database operations, API contracts |
+| **E2E test** | User-facing workflows, multi-service interactions |
+| **Manual verification** | UI/UX behavior, visual correctness, one-time infrastructure changes |
+| **Build verification** | Compilation, type checking, linting, bundle size |
+| **Deploy verification** | Service health checks, smoke tests, monitoring dashboards |
+
+### 4. Map Dependencies
+
+- Identify which tasks must complete before others can start
+- Order tasks so that each builds on a stable foundation
+- Prefer independent tasks that can run in parallel where possible
+- Flag external dependencies (other teams, services, permissions, data) that may block progress
+
+### 5. Determine Execution Order
+
+- Place foundational tasks first (types, schemas, interfaces, shared utilities)
+- Follow with implementation tasks (business logic, handlers, services)
+- Then integration tasks (wiring, configuration, API routes)
+- Finish with verification tasks (test suites, documentation, cleanup)
+
+### 6. Assign Required Skills
+
+Map each task to the skills needed to complete it. This enables delegation to specialized agents or helps identify what expertise is required.
+
+## Output Format
+
+```
+## Task Breakdown
+
+### Task 1: [imperative description]
+- **Acceptance criteria:**
+  - [specific, measurable criterion]
+  - [specific, measurable criterion]
+- **Verification:** [type] -- [how to verify]
+- **Dependencies:** [none | task IDs that must complete first]
+- **Skills:** [list of skills needed]
+
+### Task 2: [imperative description]
+- **Acceptance criteria:**
+  - [specific, measurable criterion]
+- **Verification:** [type] -- [how to verify]
+- **Dependencies:** [Task 1]
+- **Skills:** [list of skills needed]
+
+### Execution Order
+1. [Task 1, Task 3] (parallel -- no dependencies)
+2. [Task 2] (depends on Task 1)
+3. [Task 4] (depends on Task 2, Task 3)
+
+### External Dependencies
+- [dependency] -- [who owns it] -- [current status]
+```
+
+## Rules
+
+- Every task must have at least one acceptance criterion that can be empirically verified
+- Do not create tasks that cannot be verified -- if you cannot define how to prove it is done, the task is not well-scoped
+- Keep tasks ordered so that no task references work that has not been completed by a prior task
+- Flag any task that requires access, permissions, or external input not yet available
+- Prefer more small tasks over fewer large tasks -- smaller tasks are easier to verify and less risky to fail
+- Do not create placeholder or "TODO" tasks -- every task should describe concrete work

package/plugins/src/base/skills/task-triage/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: task-triage
+description: "8-step task triage and implementation workflow. Ensures tasks have clear requirements, dependencies, and verification plans before implementation begins."
+---
+
+# Task Triage
+
+Follow this 8-step triage process before implementing any task. Do not skip triage.
+
+## Triage Steps
+
+1. Verify you have all information needed to implement this task (acceptance criteria, design specs, environment information, dependencies, etc.). Do not make assumptions. If anything is missing, stop and ask before proceeding.
+2. Verify you have a clear understanding of the expected behavior or outcome when the task is complete. If not, stop and clarify before starting.
+3. Identify all dependencies (other tasks, services, APIs, data) that must be in place before you can complete this task. If any are unresolved, stop and raise them before starting implementation.
+4. Verify you have access to the tools, environments, and permissions needed to deploy and verify this task (e.g. CI/CD pipelines, deployment targets, logging/monitoring systems, API access, database access). If any are missing or inaccessible, stop and raise them before starting implementation.
+5. Define the tests you will write to confirm the task is implemented correctly and prevent regressions.
+6. Define the documentation you will create or update to explain the "how" and "what" behind this task so another developer understands it.
+7. If you can verify your implementation before deploying to the target environment (e.g. start the app, invoke the API, open a browser, run the process, check logs), do so before deploying.
+8. Define how you will verify the task is complete beyond a shadow of a doubt (e.g. deploy to the target environment, invoke the API, open a browser, run the process, check logs).
+
+## Implementation
+
+Use the output of the triage steps above as your guide. Do not skip triage.

package/plugins/src/base/skills/tdd-implementation/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: tdd-implementation
+description: "Test-Driven Development implementation workflow. RED: write failing test, GREEN: minimum code to pass, REFACTOR: clean up. Includes task metadata requirements, verification, and atomic commit practices."
+---
+
+# TDD Implementation
+
+Implement code changes using the Test-Driven Development (RED/GREEN/REFACTOR) cycle. This skill defines the complete workflow from task metadata validation through atomic commit.
+
+## Task Metadata
+
+Each task you work on must have the following in its metadata:
+
+```json
+{
+  "plan": "<plan-name>",
+  "type": "spike|bug|task|epic|story",
+  "acceptance_criteria": ["..."],
+  "relevant_documentation": "",
+  "testing_requirements": ["..."],
+  "skills": ["..."],
+  "learnings": ["..."],
+  "verification": {
+    "type": "test|ui-recording|test-coverage|api-test|manual-check|documentation",
+    "command": "the proof command",
+    "expected": "what success looks like"
+  }
+}
+```
+
+All fields are mandatory — empty arrays are ok. If any are missing, ask the agent team to fill them in and wait to get a response.
+
+## Workflow
+
+1. **Verify task metadata** — All fields are mandatory. If any are missing, ask the agent team to fill them in and wait to get a response.
+2. **Load skills** — Load the skills in the `skills` property of the task metadata.
+3. **Read before writing** — Read existing code before modifying it. Understand acceptance criteria, verification, and relevant research.
+4. **Follow existing patterns** — Match the style, naming, and structure of surrounding code.
+5. **One task at a time** — Complete the current task before moving on.
+6. **RED** — Write a failing test that captures the expected behavior from the task description. Focus on testing behavior, not implementation details.
+7. **GREEN** — Write the minimum production code to make the test pass.
+8. **REFACTOR** — Clean up while keeping tests green.
+9. **Verify empirically** — Run the task's proof command and confirm expected output.
+10. **Update documentation** — Add/Remove/Modify all relevant JSDoc preambles, explaining "why", not "what".
+11. **Update the learnings** — Add what you learned during implementation to the `learnings` array in the task's `metadata.learnings`. These should be things that are relevant for other implementers to know.
+12. **Commit atomically** — Once verified, run the `/git-commit` skill.
+
+## TDD Cycle
+
+**Always write failing tests before implementation code.** This is mandatory, not optional.
+
+```text
+TDD Cycle:
+1. RED: Write a failing test that defines expected behavior
+2. GREEN: Write the minimum code to make the test pass
+3. REFACTOR: Clean up while keeping tests green
+```
+
+### RED Phase
+
+- Write a test that captures the expected behavior from the task description
+- Focus on testing behavior, not implementation details
+- The test must fail before you write any production code
+- If the imported module doesn't exist, Jest reports 0 tests found (not N failed) — this is expected RED behavior
+
+### GREEN Phase
+
+- Write the minimum production code to make the test pass
+- Do not optimize, do not add features beyond what the test requires
+- The goal is the simplest code that makes the test green
+
+### REFACTOR Phase
+
+- Clean up code while keeping all tests green
+- Remove duplication, improve naming, simplify structure
+- Run tests after every refactor step to confirm nothing breaks
+
+## When Stuck
+
+- Re-read the task description and acceptance criteria
+- Check relevant research for reusable code references
+- Search the codebase for similar implementations
+- Ask the team lead if the task is ambiguous — do not guess

package/plugins/src/base/skills/test-strategy/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: test-strategy
+description: "Test strategy design. Coverage matrix, edge cases, TDD sequence planning, test quality review. Behavior-focused testing over implementation details."
+---
+
+# Test Strategy
+
+Design test strategies, write tests, and review test quality.
+
+## Analysis Process
+
+1. **Read existing tests** -- understand the project's test conventions (describe/it structure, naming, helpers)
+2. **Identify test types needed** -- unit, integration, E2E based on the scope of changes
+3. **Map edge cases** -- boundary values, empty inputs, error states, concurrency scenarios
+4. **Check coverage gaps** -- run existing tests to understand current coverage of affected files
+5. **Design verification commands** -- proof commands that empirically demonstrate the code works
+
+## Test Writing Process
+
+1. **Analyze the source file** to understand its functionality
+2. **Identify untested code paths**, edge cases, and error conditions
+3. **Write comprehensive, meaningful tests** (not just coverage padding)
+4. **Follow the project's existing test patterns** and conventions
+5. **Ensure tests are readable and maintainable**
+
+## Output Format
+
+Structure findings as:
+
+```text
+## Test Analysis
+
+### Test Matrix
+| Component | Test Type | What to Test | Priority |
+|-----------|-----------|-------------|----------|
+
+### Edge Cases
+- [edge case] -- why it matters
+
+### Coverage Targets
+- `path/to/file.ts` -- current: X%, target: Y%
+
+### Test Patterns (from codebase)
+- Pattern: [description] -- found in `path/to/test.spec.ts`
+
+### Verification Commands
+| Task | Proof Command | Expected Output |
+|------|--------------|-----------------|
+
+### TDD Sequence
+1. [first test to write] -- covers [behavior]
+2. [second test] -- covers [behavior]
+```
+
+## Rules
+
+- Always run `bun run test` to understand current test state before recommending or writing new tests
+- Match existing test conventions -- do not introduce new test patterns
+- Every test must have a clear "why" -- no tests for testing's sake
+- Focus on testing behavior, not implementation details
+- Verification commands must be runnable locally (no CI/CD dependencies)
+- Prioritize tests that catch regressions over tests that verify happy paths
+- Write comprehensive tests, not just coverage padding