openhermes 2.8.0 → 4.0.1

package/harness/skills/oh-expert/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: oh-expert
+description: "AI-expert built-in: shared vocabulary for self-diagnosis, failure modes, attention dynamics, and working patterns"
+tier: 2
+triggers:
+  - "why did you get that wrong"
+  - "diagnose yourself"
+  - "are you sure"
+  - "stop agreeing with me"
+  - "sycophancy"
+  - "hallucination"
+  - "attention"
+  - "smart zone"
+---
+
+# oh-expert
+
+Shared AI-coding vocabulary for agent self-diagnosis. Every failure mode maps to a specific cause and fix. Use this vocabulary precisely — vague terms ("hallucination" alone, "wrong") have no diagnostic value.
+
+## Failure Modes
+
+### Sycophancy
+Confidently agreeable output. The model was trained to favor answers humans liked — agreement is rewarded even when wrong.
+
+**Surfaces as:**
+- Caving under pushback — reverses a correct answer when you say "are you sure?"
+- Praising bad input — agrees a broken plan is brilliant before analyzing it
+- Biased framing — review skews positive when you signal authorship
+- Mimicry — repeats your mistakes back as confirmation
+
+**Diagnostic test:** Would I have said this without the user's steer? If only tone/framing changed, it is sycophancy.
+
+**Fix:** Hide your preferences. Re-ask neutrally — "review this code" not "is this code good?"
+
+### Hallucination (two flavors)
+Confidently-wrong output. Two flavors with different causes and fixes:
+
+- **Factuality hallucination** — invented/wrong facts (fake function, wrong API, fake citation). Caused by parametric knowledge gaps. Fix: load contextual knowledge (read docs, read the file).
+
+- **Faithfulness hallucination** — output drifts from loaded context, user instructions, or own prior reasoning. Symptom of attention degradation. Fix: clear or compact.
+
+**Avoid:** "Hallucination" as bare synonym for "wrong" — without naming the flavor the term has no diagnostic value.
+
+### Attention Degradation
+As a session grows, each token's attention budget spreads across more competitors. Signal on meaningful relationships shrinks; noise from irrelevant context crowds in.
+
+**Surfaces as:** The smart zone → dumb zone drift. Inventing generics not in the type file. Ignoring schema pasted at the top.
+
+**Fix:** Clear and reload. Do NOT add more docs — the problem is not missing information, it is buried signal.
+
+### Smart Zone / Dumb Zone
+Early in a session the agent is sharp and focused (smart zone). As session grows it drifts into a dumb zone: sloppier, forgetful, more faithfulness hallucinations.
+
+**Threshold:** On frontier models, the dumb zone commonly begins around 100k tokens.
+
+**Self-diagnosis cue:** "It nailed the first three components and butchered the fourth" = out of smart zone.
+
+**Fix:** Clear or compact. Do not push through.
+
+### Non-determinism
+Same input can produce different output. A property of how models generate text. No setting to disable it.
+
+**Self-diagnosis cue:** "The model has been awful today" → probably not a worse version, just the distribution. Try again tomorrow.
+
+**Avoid:** Over-narrativizing. A string of bad runs is not proof something changed.
+
+### Knowledge Cutoff
+The date past which a model has no parametric knowledge. Post-cutoff libraries/APIs are fabrication traps.
+
+**Self-diagnosis cue:** "It keeps writing v3 SDK syntax — we are on v5." → v5 shipped after cutoff. Load current docs.
+
+## Working Patterns
+
+### Progressive Disclosure
+AGENTS.md pays token cost every turn. Put infrequently used instructions behind context pointers (skills).
+
+### Handoff
+Transferring context from one session to another with no return path. Use when: planning session is getting heavy, role switching, kicking off AFK runs. Always write a structured artifact.
+
+### Compaction
+A handoff done in-memory: previous session is summarized and seeds a fresh session. Lossy — detail traded for headroom. Compact manually to control what is kept.
+
+### Subagent
+An agent spawned by another agent via tool call. Runs in own session with own context window. Reports a single result back. Cannot spawn further subagents (one level deep). Use to isolate context.
+
+### Skill vs Tool
+- **Skill**: instructions the agent reads (loaded on demand)
+- **Tool**: function the agent calls (always available)
+Do not confuse them.
+
+## Diagnostic Map
+
+| Symptom | Likely Cause | First Move |
+|---|---|---|
+| Reverses answer under pushback | Sycophancy | Re-ask neutrally, hide preference |
+| Invents things in the loaded doc | Faithfulness hallucination / attention degradation | Clear or compact |
+| Invents things not in any doc | Factuality hallucination / parametric gap | Load relevant docs |
+| Sharp early, sloppy late | Smart zone → dumb zone drift | Compact, do not push through |
+| Different results same input | Non-determinism (normal) | Try again |
+| Writes old API syntax | Knowledge cutoff | Load current docs |
+| Agrees with bad ideas | Sycophancy | Phrase prompts neutrally |
+| Ignores context at top of window | Attention budget exhausted | Clear or move critical context closer |
+
+## Avoid These Terms (imprecise or wrong)
+
+| Instead of | Use |
+|---|---|
+| "Hallucination" alone | Factuality hallucination or faithfulness hallucination |
+| "Sycophancy" for any pleasing wrong answer | Only when diagnostic test confirms |
+| "Tool" for a skill | Skill = instructions read; Tool = function called |
+| "Memory" (for context window) | Context window |
+| "Working memory" | Contextual knowledge |
+| "Background agent" | AFK |
+
+## Routing
+
+| Outcome | Route |
+|---------|-------|
+| pass | → oh-builder (implement fix) or oh-gauntlet (re-test) |
+| fail | → oh-expert (re-diagnose — load fresh context) |
+| blocker | → surface to user |

package/harness/skills/oh-freeze/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: oh-freeze
+description: "Restrict file edits to a specific directory for the session"
+---
+
+# oh-freeze
+
+## When to Use
+When debugging a specific module and you want to prevent accidentally "fixing" unrelated code. Scopes all Edit/Write operations to one directory.
+
+## Workflow
+1. Specify target directory to freeze
+2. All Edit/Write operations outside that directory are blocked
+3. User can explicitly approve cross-boundary edits
+4. Unfreeze to release the boundary
+
+## Anti-patterns
+- Freezing too broadly (defeats the purpose)
+- Forgetting to unfreeze when task scope expands
+- Using freeze as a substitute for git discipline
+
+## Routing
+
+| Outcome | Route |
+|---------|-------|
+| pass | → [return to prior skill — scope lock active] |
+| fail | → [surface issue — freeze not applied] |
+| blocker | → surface to user |

package/harness/skills/oh-gauntlet/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: oh-gauntlet
+description: "Rigorous multi-axis testing gauntlet: unit, integration, edge cases, dual-axis review. Loops until done or blocker."
+tier: 4
+benefits-from: [oh-expert, oh-builder]
+triggers:
+  - "gauntlet"
+  - "test everything"
+  - "rigorous testing"
+  - "review all angles"
+  - "qa"
+  - "full review"
+  - "run the gauntlet"
+  - "validate"
+---
+
+# oh-gauntlet
+
+Runs the current build through a multi-axis gauntlet: tests, edge cases, standards review, spec review. Spawns parallel sub-agents for independent axes. Loops until everything passes or a blocker is surfaced.
+
+## Gauntlet Stages
+
+Each stage runs independently (parallel where possible). A stage that fails loops: fix → re-run → verify → pass or blocker.
+
+### Stage 1: Test Suite
+Run all existing tests. Check both that they pass and that they actually test the right things:
+- **Unit tests** — do they pass? Are they testing behavior or implementation?
+- **Integration tests** — do the real code paths work end-to-end?
+- **Edge case coverage** — empty states, error states, boundary conditions, concurrency
+
+If tests are missing or weak, flag what should be added. Do not add them here — surface as finding.
+
+### Stage 2: Dual-Axis Review (parallel sub-agents)
+
+Spawn two sub-agents simultaneously:
+
+**Standards sub-agent:** Read the repo's documented standards (CONTEXT.md, AGENTS.md, eslint config, ADRs, STYLE.md, CONVENTIONS.md). Then read the diff. Report every place the diff violates a documented standard. Cite the standard source. Distinguish hard violations from judgement calls.
+
+**Spec sub-agent:** Read the spec source (plan.md, issue, PRD, or user's description). Then read the diff. Report: (a) requirements that are missing or partial, (b) scope creep (behavior not asked for), (c) requirements that look implemented but wrong. Quote the spec.
+
+Report both axes independently — do not merge or rank. A change can pass one and fail the other.
+
+### Stage 3: Edge Case Sweep
+Systematic edge case analysis for the changed code:
+- Error states — what happens when inputs are invalid, files are missing, network fails?
+- Concurrency — race conditions, deadlocks, stale state
+- Security — injection, auth bypass, data leakage, permission escalation
+- Performance — N+1 queries, unbounded loops, memory leaks, unnecessary allocations
+- State transitions — invalid state transitions, partial updates, rollback gaps
+
+For each finding: severity (critical/major/minor), location, reproduction path.
+
+### Stage 4: QA Sweep (tiered)
+Systematic testing with iterative fix-verify cycles. Choose tier based on risk:
+
+- **Quick** — critical/high severity flows only
+- **Standard** — critical + medium severity, full edge case sweep
+- **Exhaustive** — all of the above + cosmetic, edge cases, cross-browser
+
+1. Execute tests against each user flow, edge case, error state
+2. Log findings with severity, reproduction steps, evidence
+3. Fix highest-severity first, commit each fix atomically
+4. Re-verify after each fix — confirm fix, check for regressions
+5. Produce health scores (before/after)
+
+### Stage 5: Canary (post-deploy)
+If deploying to production:
+
+1. **Set baseline** — capture pre-deploy screenshots and metrics
+2. **Deploy check** — verify deploy completed successfully
+3. **Canary run** — navigate key user flows, capture screenshots, log console errors
+4. **Compare** — diff against pre-deploy baselines
+5. **Alert** — surface anomalies, performance regressions, new errors
+6. **Recovery** — if critical issues found, suggest rollback
+
+Output: health status, screenshots (before/after), error log, performance diff, ship/no-go verdict.
+
+### Stage 6: Manual Verification Checklist
+Based on the plan's verification criteria or spec:
+- [ ] Happy path works end-to-end
+- [ ] Error path degrades gracefully
+- [ ] No regression in adjacent areas
+- [ ] Logging/monitoring covers failure modes
+- [ ] Documentation matches behavior (if applicable)
+
+## Loop Protocol
+
+1. Run all 6 stages (skip Stage 5 if not deploying)
+2. Collect findings by severity
+3. If 0 criticals and 0 majors → DONE
+4. If criticals or majors exist → fix highest severity first
+5. After fix → re-run affected stages only
+6. If fix is impossible within scope → surface BLOCKER
+
+## Blocker Protocol
+
+```
+BLOCKER: <what failed>
+Context: <what was attempted, why it cannot proceed>
+Options:
+  A: <scope reduction>
+  B: <alternative approach>
+  C: <dependency change>
+```
+
+## Anti-patterns
+- Running stages sequentially when they can be parallel (Standards and Spec reviews are independent)
+- Mixing Standards and Spec findings (keep axes separate — one can pass while the other fails)
+- Skipping edge case sweep because tests pass (tests confirm behavior, not absence of edge cases)
+- Ignoring minors because no criticals exist (accumulated minors signal design debt)
+- Pushing through critical failures without surfacing blocker
+
+## Routing
+
+| Outcome | Route |
+|---------|-------|
+| pass | → oh-ship (all checks pass) |
+| fail | → oh-builder (fix issues found) |
+| blocker | → surface to user |

package/harness/skills/oh-grill/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: oh-grill
+description: "Stress-test plans and designs through relentless Socratic questioning. Sharpens assumptions, flags blind spots, updates domain docs."
+tier: 3
+benefits-from: [oh-expert, oh-planner]
+triggers:
+  - "grill"
+  - "stress test this plan"
+  - "challenge this"
+  - "grill me"
+  - "poke holes"
+  - "interrogate"
+---
+
+# oh-grill
+
+Stress-tests plans and designs through relentless Socratic questioning. Two modes: plain interrogate (quick) or interrogate + update domain docs (thorough).
+
+## When to Use
+Before committing to a plan or design. When the user says "it is writing exactly what I asked for and it is still wrong" — the design concept is not shared yet. Cheaper to resolve in conversation than in code.
+
+## Modes
+
+### Mode A: Grill (quick)
+Challenge the plan without touching files.
+
+1. Read the plan or design doc
+2. Interview the user one decision at a time — each answer reveals new branches
+3. Resolve each branch before moving on
+4. Surface: contradictions, blind spots, unstated assumptions, ambiguous terms
+5. Propose a recommended answer for each decision
+6. Output: verified, stress-tested plan with flagged ambiguities
+
+### Mode B: Grill with Docs (thorough)
+Same as Mode A, but persists decisions to CONTEXT.md and ADRs, and extracts a DDD ubiquitous-language glossary.
+
+1. Load existing CONTEXT.md and ADRs
+2. Grill through the decision tree — each resolved decision may:
+   - Update CONTEXT.md domain terms (sharpen fuzzy language)
+   - Create a new ADR for architectural decisions
+   - Flag an ambiguity in the domain glossary
+3. **Ubiquitous Language extraction** — after the decision tree resolves, scan the conversation for domain-relevant nouns, verbs, and concepts:
+   - Identify problems: same word for different concepts (ambiguity), different words for same concept (synonyms), vague or overloaded terms
+   - Propose a canonical glossary with grouped tables (by subdomain, lifecycle, or actor)
+   - Write an example dialogue (3-5 exchanges) between dev and domain expert showing natural term usage
+   - Write flagged ambiguities section
+4. Persist changes to CONTEXT.md immediately as language firms up
+5. Output: updated CONTEXT.md + new ADRs + UBIQUITOUS_LANGUAGE.md (if significant terms emerged) + verified plan with resolution trail
+
+## Technique
+
+- Ask one question at a time
+- Propose a recommended answer for each decision
+- Walk the full decision tree before accepting the design
+- Reference domain glossary from CONTEXT.md when terms are ambiguous
+- Cross-reference with existing ADRs when architecture is at stake
+
+## When NOT to Use
+- When you already have a clear, vetted plan and need execution
+- When the user needs a builder, not a critic
+- For trivial decisions that don't change the design's shape
+
+## Anti-patterns
+- Grilling for the sake of grilling (redundant with existing reviews)
+- Asking questions you could answer by reading the plan or codebase
+- Creating ADRs for trivial decisions (not every choice is architecture)
+- Polishing CONTEXT.md prose before concepts are settled
+- Updating domain terms mid-discussion — let the conversation resolve first
+- Not distinguishing between "must resolve now" vs "figure out later"
+
+## Routing
+
+| Outcome | Route |
+|---------|-------|
+| pass | → oh-planner (revise plan based on feedback) |
+| fail | → oh-expert (resolve confusion or blind spot) |
+| blocker | → surface to user |

package/harness/skills/oh-guard/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: oh-guard
+description: "Safety confirmation mode — warn before destructive operations"
+---
+
+# oh-guard
+
+## When to Use
+When touching production, running destructive commands, or working in shared environments. Combines warning prompts with directory-scoped edit locks.
+
+## Workflow
+1. **Enable guard mode** — set safety level (careful / freeze / full guard)
+2. **Destructive command warnings** — intercept rm -rf, DROP TABLE, force-push, git reset --hard, kubectl delete
+3. **Directory scope lock** — restrict file edits to specified directory (freeze)
+4. **User override** — user can approve or deny each operation
+
+## Modes
+- **Careful** — warn before destructive commands
+- **Freeze** — restrict edits to one directory
+- **Guard** — both careful + freeze
+
+## Anti-patterns
+- Disabling guard because "I know what I'm doing" (narrator: they didn't)
+- Running prod commands outside guard mode
+- Ignoring warnings about irreversible operations
+
+## Routing
+
+| Outcome | Route |
+|---------|-------|
+| pass | → [return to prior skill — guard mode active] |
+| fail | → [surface warning — operation denied] |
+| blocker | → surface to user |

package/harness/skills/oh-handoff/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: oh-handoff
+description: "Compact session state into a structured handoff document"
+---
+
+# oh-handoff
+
+## When to Use
+When switching contexts, ending a session, or passing work to another agent or developer. Produces a compact summary that captures everything needed to resume.
+
+## Handoff Document Structure
+- **Context** — what were we doing?
+- **State** — what's done, what's pending, what's blocked?
+- **Decisions** — key decisions made this session
+- **Artifacts** — files changed, created, or referenced
+- **Next steps** — ordered list of what to do next
+- **Risks** — things to be aware of
+
+## Output
+A `HANDOFF.md` or structured text block with all resume-relevant information.
+
+## Anti-patterns
+- Writing a novel (handoff should be scannable in 30 seconds)
+- Omitting decisions (why we chose X over Y is critical context)
+- No next steps ("figure it out" is not a handoff)
+
+## Routing
+
+| Outcome | Route |
+|---------|-------|
+| pass | → [end of session — intentional terminal] |
+| fail | → [surface blocker — handoff incomplete] |
+| blocker | → surface to user |

package/harness/skills/oh-health/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: oh-health
+description: "Code quality dashboard: runs project tools (typecheck, lint, test, dead code detection), computes weighted composite 0-10 score, persists history, shows trend. Read-only — no fixes."
+tier: 2
+triggers:
+  - "health check"
+  - "code quality"
+  - "quality dashboard"
+  - "how healthy is the codebase"
+  - "run all checks"
+  - "health"
+---
+
+# oh-health
+
+Staff Engineer who owns the CI dashboard. Runs every available project tool, scores results 0-10, computes weighted composite, persists history for trend tracking. Read-only — the user decides what to act on.
+
+## Process
+
+### Step 1: Detect Health Stack
+Auto-detect available tools:
+- **Type checker** — `tsc --noEmit` (tsconfig.json present), `mypy` (pyproject.toml), or none
+- **Linter** — biome, eslint, ruff/pylint, or none
+- **Test runner** — from package.json scripts, pytest, cargo test, go test
+- **Dead code** — knip, or none
+- **Shell lint** — shellcheck for .sh files
+
+Present detected tools. Optionally persist to CLAUDE.md as `## Health Stack` section for future runs.
+
+### Step 2: Run Tools
+Run each tool sequentially (some share resources). Capture exit code + output summary for each.
+
+### Step 3: Score Each Category
+
+| Category | Weight | 10 | 7 | 4 | 0 |
+|---|---|---|---|---|---|
+| Type check | 22% | Clean | <10 errors | <50 errors | 50+ |
+| Lint | 18% | Clean | <5 warnings | <20 warnings | 20+ |
+| Tests | 28% | All pass | >95% pass | >80% pass | <=80% |
+| Dead code | 13% | Clean | <5 unused | <20 unused | 20+ |
+| Shell lint | 9% | Clean | <5 issues | 5+ issues | N/A |
+| Framework | 10% | Native default | Config override | Manual | Unmanaged |
+
+Skip unavailable categories and redistribute weight proportionally among remaining.
+
+### Step 4: Present Dashboard
+
+```
+CODE HEALTH DASHBOARD
+═════════════════════
+Project: <name>
+Branch:  <branch>
+Date:    <date>
+
+Category      Score   Status     Details
+──────────    ─────   ────────   ───────
+Type check    10/10   CLEAN      0 errors
+Lint           8/10   WARNING    3 warnings
+Tests         10/10   CLEAN      47/47 passed
+Dead code      7/10   WARNING    4 unused exports
+
+COMPOSITE: 9.1 / 10
+```
+
+Status labels: 10=CLEAN, 7-9=WARNING, 4-6=NEEDS WORK, 0-3=CRITICAL.
+
+### Step 5: Persist History
+Append one JSONL line to `.opencode/health-history.jsonl`:
+```json
+{"ts":"2026-05-14T14:30:00Z","branch":"main","score":9.1,"typecheck":10,"lint":8,"test":10,"deadcode":7,"duration_s":23}
+```
+
+### Step 6: Trend Analysis + Recommendations
+Read last 10 history entries. Show trend table. For regressions, identify declining categories and specific errors. Rank improvement suggestions by impact (weight × score deficit).
+
+## Rules
+
+- **Read-only.** No fixes. Dashboard and recommendations only.
+- **Wrap, don't replace.** Run the project's own tools. Never substitute your own analysis.
+- **Skipped is not failed.** Tool not installed → skip gracefully, redistribute weight.
+- **Show raw output for failures.** Include tool output so user can act without re-running.
+- **Trends require history.** First run: "No trend data yet. Run again after changes to track progress."
+
+## Routing
+
+| Outcome | Route |
+|---------|-------|
+| pass | → [report score to user] |
+| fail | → oh-investigate (deepen on degraded metrics) |
+| blocker | → surface to user |

package/harness/skills/oh-init/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: oh-init
+description: "Initialize project for agent-assisted development: scaffold CONTEXT.md, AGENTS.md, docs/adr/, configure issue tracker and triage labels."
+tier: 2
+triggers:
+  - "init project"
+  - "setup project"
+  - "initialize"
+  - "onboard"
+  - "scaffold"
+---
+
+# oh-init
+
+Per-repo setup for agent-assisted development. Run once per repo. Walks through configuration decisions one at a time.
+
+## Process
+
+### 1. Issue Tracker
+Detect the git hosting platform:
+- **GitHub** — `gh` CLI
+- **GitLab** — `glab` CLI
+- **Local markdown** — files under `.scratch/<feature>/`
+- **Other** — freeform workflow description
+
+Confirm with the user. Write the result to `docs/agents/issue-tracker.md`.
+
+### 2. Triage Labels
+The `triage` skill uses these label strings to move issues through a state machine:
+- `needs-triage` — maintainer needs to evaluate
+- `needs-info` — waiting on reporter
+- `ready-for-agent` — fully specified, AFK-ready
+- `ready-for-human` — needs human implementation
+- `wontfix` — will not be actioned
+
+If the repo already has different label names, map them. Write to `docs/agents/triage-labels.md`.
+
+### 3. Domain Docs
+Configure how the project organizes domain language:
+- **Single-context** — one `CONTEXT.md` + `docs/adr/` at repo root
+- **Multi-context** — `CONTEXT-MAP.md` pointing to per-context files
+
+Scaffold `CONTEXT.md` with project name, domain description, and placeholder glossary terms. Create `docs/adr/` directory with ADR template.
+
+Write to `docs/agents/domain.md`.
+
+### 4. Agent Skills Block
+Add a `## Agent skills` section to `AGENTS.md` (or `CLAUDE.md` if it exists):
+
+```markdown
+## Agent skills
+
+### Issue tracker
+<summary>. See docs/agents/issue-tracker.md.
+
+### Triage labels
+<summary>. See docs/agents/triage-labels.md.
+
+### Domain docs
+<summary>. See docs/agents/domain.md.
+```
+
+### 5. Decision Record
+Record: "oh-init completed for project \<name\> on \<date\>."
+
+## Anti-patterns
+- Running init without understanding the project domain
+- Scaffolding CONTEXT.md without populating any terms
+- Creating ADR directory but never writing ADRs
+- Creating both AGENTS.md and CLAUDE.md — edit the one that exists
+
+## Routing
+
+| Outcome | Route |
+|---------|-------|
+| pass | → [done — one-time project setup] |
+| fail | → [retry with user corrections] |
+| blocker | → surface to user |

package/harness/skills/oh-investigate/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: oh-investigate
+description: "Systematic bug diagnosis with root cause investigation"
+---
+
+# oh-investigate
+
+## When to Use
+When a bug is reported, a test fails, or unexpected behavior occurs. Use this before attempting any fix.
+
+## Workflow
+1. **Reproduce** — get a reliable reproduction case (script, test, or steps)
+2. **Minimise** — strip away unrelated code until the minimal reproduction remains
+3. **Hypothesise** — list possible root causes, rank by likelihood
+4. **Instrument** — add logging, assertions, or debug output to test hypothesis
+5. **Fix** — implement the smallest correct change addressing root cause
+6. **Regression test** — verify fix doesn't break existing behavior
+7. **Document** — log the root cause and fix in the handoff, issue, or docs that are actually in scope
+
+## Iron Law
+No fixes without root cause. Surface-level fixes compound into technical debt.
+
+## Anti-patterns
+- Fixing symptoms instead of causes (the same bug reappears next week)
+- Changing code without reproducing the bug first
+- "Shotgun" debugging — changing multiple things hoping one sticks
+- Not documenting root cause for future reference
+
+## Routing
+
+| Outcome | Route |
+|---------|-------|
+| pass | → oh-builder (implement the fix) |
+| fail | → oh-expert (deepen diagnosis) |
+| blocker | → surface to user |

package/harness/skills/oh-issue/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: oh-issue
+description: "Break a plan, spec, or PRD into independently-grabbable GitHub issues"
+---
+
+# oh-issue
+
+## When to Use
+When a plan exists and needs to be broken into actionable issues. Uses tracer-bullet vertical slices for independent work items.
+
+## Workflow
+1. Read the plan or PRD
+2. Identify vertical slices — self-contained features that ship independently
+3. Write each issue with: clear title, acceptance criteria, implementation notes, dependencies
+4. Use `gh issue create` to publish each issue
+5. Label and milestone each issue appropriately
+
+## Issue Structure
+- **Title**: action-oriented ("Add user authentication API")
+- **Acceptance criteria**: concrete, testable ("User can sign up with email + password")
+- **Implementation notes**: pointers for the implementer
+- **Dependencies**: what must be done first
+- **Labels**: type, priority, area
+
+## Anti-patterns
+- Horizontal slicing (DB layer / API layer / UI layer — no one ships a layer)
+- Issues too large (3+ days) or too small (< 1 hour)
+- Writing issues without acceptance criteria
+
+## Routing
+
+| Outcome | Route |
+|---------|-------|
+| pass | → [done — issues published to tracker] |
+| fail | → oh-planner (re-spec unclear slices) |
+| blocker | → surface to user |