@homericintelligence/athena-opencode 0.4.4 → 0.5.1

package/skills/systematic-debugging/SKILL.md

@@ -1,198 +1,262 @@
 ---
 name: systematic-debugging
 license: BSD-3-Clause
-description: Investigate root cause before fixing bugs or unexpected behavior. Requires the Mnemosyne knowledge backend through advise and fails closed when it cannot be prepared.
+description: Investigate root cause before you repair a bug or unexpected behavior. This skill requires the Mnemosyne knowledge backend through advise. Stop if the backend cannot be prepared.
 argument-hint: <description of the bug or failure>
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
 ---
 
-# Systematic Debugging
+# Systematic debugging
 
 ## Overview
 
-Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+A repair without evidence wastes time and can create a new bug. A repair of only the symptom can
+hide the root cause.
 
-**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+Apply the [ASD-STE100 technical-English policy](../TECHNICAL_ENGLISH.md) to this skill and to
+all prose that it produces.
 
-**Violating the letter of this process is violating the spirit of debugging.**
+## Working rules
 
-## Before Starting
+Find the root cause before you attempt a repair. Do not repair only the symptom. Follow each
+required step in this process.
+
+## Engineering principles
 
-Run `advise` with the error description. Failure to prepare the required knowledge backend is a
-blocking error, not permission to skip prior-knowledge search.
+Use Athena's [canonical engineering-principles catalog](../_support/docs/principles/README.md) for the
+principle definitions. Use these principles in this workflow:
 
-## The Iron Law
+- [P012 — Evidence Before Modification](../_support/docs/principles/README.md#p012): Before you select a
+  repair, examine symptoms, changes, contracts, and repository guidance.
+- [P015 — Architecture Conformance](../_support/docs/principles/README.md#p015): Before you change the
+  architecture, compare the failure path with the repository boundaries.
+- [P022 — Test Behavior, Not Implementation](../_support/docs/principles/README.md#p022): Reproduce the
+  observable contract. Add a test for this contract. Do not add a test for the private
+  implementation.
+- [P029 — Generalize Error Policy; Preserve Specific Cause](../_support/docs/principles/README.md#p029):
+  Use a stable error policy at the boundary. Keep the initial cause.
+- [P031 — Propagate Rather Than Swallow](../_support/docs/principles/README.md#p031): If this layer cannot
+  fully recover from the failure, propagate the failure.
+- [P047 — Observability Is Part of Correctness](../_support/docs/principles/README.md#p047): Collect the
+  minimum evidence that is necessary to find the fault. Correlate the evidence. Use a structured
+  data format. Do not include sensitive data.
+- [P065 — Verify Before Claiming Completion](../_support/docs/principles/README.md#p065): Before you tell the
+  user that you corrected the fault, do the initial reproduction again. Then, do the applicable
+  repository checks.
+- [P072 — Technical Evidence Over Preference](../_support/docs/principles/README.md#p072): Use only collected
+  evidence to accept or reject a hypothesis.
 
-```text
-NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
-```
+## Before you start
 
-If you haven't completed Phase 1, you cannot propose fixes.
+Run `advise` with the error description. If you cannot prepare the required knowledge backend,
+stop. Do not skip the prior-knowledge search.
 
-## When to Use
+## Required sequence
 
-Use for ANY technical issue:
+Complete phase 1 before you propose a repair.
 
-- Test failures
-- Bugs in production
-- Unexpected behavior
-- Performance problems
-- Build failures
-- Integration issues
+## When to use
 
-**Use this ESPECIALLY when:**
+Use this skill for all technical issues, including:
 
-- 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
+- A test fails.
+- A bug occurs in production.
+- The product has unexpected behavior.
+- The product has a performance problem.
+- A build fails.
+- An integration fails.
 
-## The Four Phases
+Use this skill especially in these conditions:
 
-You MUST complete each phase before proceeding to the next.
+- You are under time pressure.
+- A repair appears obvious before an investigation.
+- You already attempted multiple repairs.
+- A previous repair did not work.
+- You do not fully understand the issue.
 
-### Phase 1: Root Cause Investigation
+## Workflow
 
-**BEFORE attempting ANY fix:**
+Complete each phase before you continue to the next phase.
 
-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
+### Phase 1: Root cause investigation
 
-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
+Before you attempt a repair, complete these steps:
 
-3. **Check Recent Changes**
-   - What changed that could cause this?
-   - `git diff`, recent commits
-   - New dependencies, config changes
-   - Environmental differences
+1. Record these items from the complete failure output:
 
-4. **Gather Evidence in Multi-Component Systems**
+   - each error and warning;
+   - the complete stack trace;
+   - line numbers;
+   - file paths;
+   - error codes.
 
-   **WHEN system has multiple components:**
+2. Do not skip an error or warning. An error message can identify the cause.
+3. Reproduce the failure consistently.
+4. Record the exact conditions, steps, and frequency of the failure.
+5. If you cannot reproduce the failure, collect more data.
+6. Do not guess the cause.
+7. Compare the failed state with recent repository history.
+8. Inspect these possible sources of the failure:
 
-   **BEFORE proposing fixes, add diagnostic instrumentation:**
+   - `git diff`;
+   - recent commits;
+   - new dependencies;
+   - configuration changes;
+   - environment differences.
 
-   ```text
-   For EACH component boundary:
-     - Log what data enters component
-     - Log what data exits component
-     - Verify environment/config propagation
-     - Check state at each layer
+9. If the system has multiple components, isolate the failed boundary.
+10. Before you propose a repair, add only the minimum non-sensitive diagnostic instrumentation that
+   [P047 — Observability Is Part of Correctness](../_support/docs/principles/README.md#p047) requires.
+11. At each component boundary:
 
-   Run once to gather evidence showing WHERE it breaks
-   THEN analyze evidence to identify failing component
-   THEN investigate that specific component
-   ```
+    - log the input data;
+    - log the output data;
+    - verify the transfer of environment and configuration data;
+    - examine the state at each layer.
+
+12. Run the instrumented reproduction one time to collect evidence.
+13. Use the evidence to identify the failed component.
+14. Investigate that component.
+15. If an incorrect value is deep in the call stack, trace the value back to its source.
+16. Identify where the incorrect value starts and which caller supplied it.
+17. Continue the trace until you find the source.
+18. Identify the source as the repair location.
+19. Do not repair only the symptom.
+
+### Phase 2: Pattern analysis
+
+Identify the pattern before you make a repair:
+
+1. Find correct examples of similar code in the same repository.
+2. Read each applicable reference implementation completely.
+3. Do not read only a sample.
+4. List each difference between the correct code and the code that fails.
+5. Identify all dependencies and all configuration and environment assumptions.
+
+### Phase 3: Hypothesis and test
 
-5. **Trace Data Flow**
+Use this method to test a hypothesis:
 
-   When error is deep in call stack:
-   - Where does the bad value originate?
-   - What called this with the bad value?
-   - Keep tracing up until you find the source
-   - Fix at source, not at symptom
+1. State one hypothesis: `The root cause is X because Y.`
+2. Make the minimum possible change to test the hypothesis.
+3. Change only one variable in each test.
+4. If the result supports the hypothesis, continue to phase 4.
+5. If the result does not support the hypothesis, state a new hypothesis.
+6. If you do not understand X, state `I do not understand X.`
+7. Do not claim that you understand X.
 
-### Phase 2: Pattern Analysis
+### Phase 4: Implementation
 
-**Find the pattern before fixing:**
+Repair the root cause.
 
-1. Find working examples of similar code in the same codebase
-2. Read reference implementations completely — don't skim
-3. List every difference between working and broken code
-4. Identify all dependencies, config, environment assumptions
+Do not repair only the symptom.
 
-### Phase 3: Hypothesis and Testing
+1. Use the `test-driven-development` skill to create a regression test.
+2. Under [P026 — Regression Before Repair](../_support/docs/principles/README.md#p026), create the test
+   before the repair.
+3. Under [P022](../_support/docs/principles/README.md#p022), make the test assert observable behavior.
+4. Under [P028](../_support/docs/principles/README.md#p028), make the test cover the applicable failure
+   path.
+5. Implement one repair that corrects the root cause.
+6. Under [P065](../_support/docs/principles/README.md#p065), run this validation:
 
-**Scientific method:**
+   - Rerun the reproduction.
+   - Run the applicable test suite.
+7. Under [P027](../_support/docs/principles/README.md#p027), keep the test deterministic and isolated.
+8. Under [P067](../_support/docs/principles/README.md#p067), do not weaken tests.
+9. Under [P068](../_support/docs/principles/README.md#p068), do not bypass validation.
 
-1. **Form single hypothesis**: "I think X is the root cause because Y"
-2. **Test minimally**: Make the SMALLEST possible change to test the hypothesis
-3. **One variable at a time**: Don't fix multiple things at once
-4. **Verify before continuing**: If it worked → Phase 4. Didn't work → new hypothesis
-5. **When stuck**: Say "I don't understand X" — don't pretend to know
+If the repair changes failure behavior, complete these steps:
 
-### Phase 4: Implementation
+1. Under [P029](../_support/docs/principles/README.md#p029), generalize the policy.
+2. Under [P029](../_support/docs/principles/README.md#p029), preserve the cause.
+3. Handle the failure at the
+   [nearest responsible boundary](../_support/docs/principles/README.md#p030).
+4. [Propagate unrecovered failures](../_support/docs/principles/README.md#p031).
+5. [Handle the failure once without losing causality](../_support/docs/principles/README.md#p032).
+6. Under [P033](../_support/docs/principles/README.md#p033), preserve valid state.
+7. Select [fail-fast](../_support/docs/principles/README.md#p034),
+   [fail-closed](../_support/docs/principles/README.md#p035), or
+   [graceful degradation](../_support/docs/principles/README.md#p036).
+8. Base this selection on the correctness and security importance of the failed capability.
+
+If the repair does not correct the issue, complete these steps:
+
+1. Stop the current repair attempt.
+2. Count the failed repair attempts.
+3. If fewer than three repairs failed, return to phase 1 with the new information.
+4. After three failed repairs, start an architecture review.
 
-**Fix the root cause, not the symptom:**
+### After three failed repairs
 
-1. **Create failing test case** using the `test-driven-development` skill — it must exist before fixing
-2. **Implement single fix** addressing the root cause
-3. **Verify fix**: Test passes? No other tests broken? Issue actually resolved?
+Repeated failed repairs can show an incorrect model, a missing dependency, or an architecture
+problem. They require a new assessment. They do not prove that the architecture is incorrect.
 
-4. **If fix doesn't work:**
-   - STOP
-   - Count: How many fixes have you tried?
-   - If < 3: Return to Phase 1 with new information
-   - **If ≥ 3: STOP and question the architecture**
+Review the evidence for these conditions:
 
-5. **If 3+ fixes failed — Question Architecture:**
+- Each repair reveals new shared state, coupling, or a problem in another component.
+- A repair requires a large refactor.
+- Each repair creates a new symptom in another component.
 
-   Pattern indicating architectural problem:
-   - Each fix reveals new shared state/coupling/problem elsewhere
-   - Fixes require massive refactoring to implement
-   - Each fix creates new symptoms elsewhere
+Before another repair attempt, discuss the collected evidence with the user. If the evidence shows
+an incorrect hypothesis, return to phase 1. Propose an architecture change only if the evidence
+supports it.
 
-   STOP and discuss with user before attempting more fixes.
-   This is not a failed hypothesis — this is a wrong architecture.
+## Stop conditions
 
-## Red Flags — STOP and Follow Process
+Stop if one of these conditions applies:
 
-- "Quick fix for now, investigate later"
-- "Just try changing X and see if it works"
-- "Add multiple changes, run tests"
-- "It's probably X, let me fix that"
-- "I don't fully understand but this might work"
-- "One more fix attempt" (when already tried 2+)
-- Each fix reveals a new problem in a different place
+- You plan a temporary repair before an investigation.
+- You plan to change X only to see the result.
+- You plan to make multiple changes before a test.
+- You select a probable cause without evidence.
+- You do not understand the issue but plan a repair.
+- You plan another repair after two failed repairs.
+- Each repair reveals a new problem in a different component.
 
-**ALL of these mean: STOP. Return to Phase 1.**
+After you stop, return to phase 1.
 
-## Common Rationalizations
+## Failed approaches
 
-| Excuse | Reality |
-| -------- | --------- |
-| "Issue is simple, don't need process" | Simple issues have root causes too. |
-| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check. |
-| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
-| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
-| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Don't fix again. |
+- Do not omit this process for a simple issue. A simple issue also has a root cause.
+- Do not omit this process during an emergency. Systematic debugging is faster than repairs without
+  evidence.
+- Do not attempt a repair before the investigation. The first repair can affect the next evidence.
+- Do not make multiple repairs at the same time. You cannot identify which repair changed the
+  result, and the repairs can cause new bugs.
+- After three failed repairs, do not make another repair from a guess. Start an architecture review.
 
 ## Repository command discovery
 
-Before running a check, discover the target repository's commands from `AGENTS.md`, task runners,
-manifests, lockfiles, and CI. Prefer the command used by required CI. If sources conflict or no safe
-command is discoverable, ask the user rather than substituting Athena's own tooling.
+Before you run a check, find the target repository commands. Inspect `AGENTS.md`, task runners,
+manifests, lockfiles, and continuous integration (CI) configuration. Prefer the command that required
+CI uses.
+If the sources conflict or you cannot find a safe command, ask the user. Do not use Athena commands
+as a substitute.
 
 Keep the target repository as the current working directory. Resolve
-`scripts/repository_evidence.py` against this installed skill directory and invoke that absolute
-helper path with `PATTERN --source-root SOURCE_ROOT` to collect the latest ten commits, a diff
-bounded to that revision window, and matching source locations as JSON. Run the
-discovered repository-focused test and type-check commands directly through the host execution
-tool, retaining their complete output as evidence.
+`scripts/repository_evidence.py` against this installed skill directory. Invoke that absolute helper
+path with `PATTERN --source-root SOURCE_ROOT`. The helper collects the latest ten commits, a diff
+bounded to that revision window, and matching source locations as JSON. Run the discovered
+repository-focused test and type-check commands through the host execution tool. Keep their complete
+output as evidence.
 
-## After Resolution
+## After resolution
 
-Verify with fresh runnable evidence per the evidence-integrity policy before claiming the bug is
-fixed; rerun the failing reproduction and the repository-defined checks.
+Before you state that the bug is fixed, verify the result with fresh runnable evidence under the
+[evidence-integrity policy](../_support/docs/policies/evidence-integrity.md). Rerun the original
+reproduction. Run the repository-defined checks again.
 
-Offer to invoke `learn` when the session produced durable debugging knowledge. An indirect Learn
-invocation remains read-only and does not expand the requested scope; use Learn's delivery boundary
-when durable learning is requested. Useful lessons include:
+If the session produces durable debugging knowledge, offer to invoke `learn`. An indirect `learn`
+invocation is read-only and does not increase the requested scope. If the user requests durable
+learning, use the delivery boundary of `learn`. Useful lessons include these items:
 
-- Root cause category and symptoms
-- What diagnostic steps revealed it
-- The fix pattern
-- Any architectural issues uncovered
+- the root-cause category and symptoms;
+- the diagnostic steps that revealed the cause;
+- the repair pattern; and
+- each architecture issue that the investigation found.
 
-This prevents the same debugging session from being repeated by another agent.
+This record prevents another agent from repeating the same debugging session.
 
 ---
 

package/skills/systematic-debugging/scripts/repository_evidence.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Collect reproducible recent-change and source-pattern evidence."""
+"""Collect reproducible evidence about recent changes and source patterns."""
 
 from __future__ import annotations
 
@@ -18,7 +18,10 @@ EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904"
 def run(*arguments: str, accepted_codes: tuple[int, ...] = (0,)) -> str:
     result = run_command(arguments, capture_output=True, text=True, check=False)
     if result.returncode not in accepted_codes:
-        raise RuntimeError(result.stderr.strip() or f"{' '.join(arguments)} failed")
+        raise RuntimeError(
+            result.stderr.strip()
+            or f"The command failed. Command: {' '.join(arguments)}"
+        )
     return result.stdout
 
 
@@ -33,9 +36,11 @@ def main() -> int:
                 "git", "rev-list", "--max-count=10", "HEAD"
             ).splitlines()
         except RuntimeError as error:
-            raise RuntimeError(f"cannot resolve HEAD: {error}") from error
+            raise RuntimeError(f"The tool cannot resolve HEAD: {error}") from error
         if not recent_revisions:
-            raise RuntimeError("cannot resolve HEAD: repository has no commits")
+            raise RuntimeError(
+                "The tool cannot resolve HEAD because the repository has no commits."
+            )
         recent_commits = run("git", "log", "--oneline", "-10")
         oldest_parent = run(
             "git",