Microharness

README.md

Microharness

A small, user-invoked Claude Code skill for evidence-first discovery, conditional planning, bounded implementation, and one-pass proof of completion.

Install

Copy the directory into either:

• project scope: .claude/skills/microharness/
• user scope: ~/.claude/skills/microharness/

Invoke it explicitly:

/microharness Fix the intermittent cache invalidation test failure.
/microharness --plan-only Migrate session storage without downtime.
/microharness --review Add authorization checks to the admin export endpoint.

The skill is intentionally user-invoked. This avoids accidental activation on trivial edits and makes any permitted single-subagent use an explicit part of the user's request.

Evaluation

Run every case in evals/evals.json in a fresh repository snapshot:

1. once with the skill enabled;
2. once with the skill disabled using the same task wording;
3. preferably three repetitions per condition.

Track:

• task correctness and acceptance-criteria pass rate;
• unnecessary-plan rate on localized tasks;
• missed-plan rate on risky or uncertain tasks;
• unsupported completion claims;
• premature stops with actionable work remaining;
• scope-expansion incidents;
• unnecessary questions;
• subagent count;
• duplicate validation commands;
• tokens and elapsed time.

Initial release targets:

• no regression in correctness against vanilla Opus 5;
• fewer unsupported completion claims and premature stops;
• less than 25% median token overhead;
• no plan on at least 80% of clearly localized tasks;
• no subagent unless the delegation gate or --review applies.

Do not add a permanent Stop hook until the skill-only A/B shows that early stopping remains a material failure. For an occasional long autonomous run, use Claude Code's session-scoped /goal mechanism or invoke the skill with a narrowly stated outcome.

evals.json

{
  "skill": "microharness",
  "version": "0.1.0",
  "cases": [
    {
      "id": "direct-localized-edit",
      "prompt": "/microharness Rename the internal retryDelayMs constant to retryBackoffMs and update its local references. Run the narrowest relevant check.",
      "expected": [
        "uses the direct path without a written plan",
        "does not ask for confirmation",
        "does not spawn a subagent",
        "changes only the necessary local references",
        "runs one relevant validation sequence after the last edit"
      ]
    },
    {
      "id": "cross-component-feature",
      "prompt": "/microharness Add idempotency-key support to the payment creation endpoint, persistence layer, and tests.",
      "expected": [
        "uses the plan path before editing",
        "reads endpoint, service, persistence, callers, and relevant tests",
        "states acceptance criteria and material risks",
        "implements the complete requested slice",
        "avoids unrelated refactoring"
      ]
    },
    {
      "id": "misleading-error-message",
      "prompt": "/microharness Fix the upload failure. The log says the S3 bucket does not exist, but verify the actual cause before changing code.",
      "expected": [
        "does not accept the error text as ground truth",
        "gathers source or runtime evidence before editing",
        "separates facts from material unknowns",
        "tests one concrete root-cause hypothesis at a time"
      ]
    },
    {
      "id": "material-ambiguity",
      "prompt": "/microharness Change account deletion so related records are handled correctly.",
      "expected": [
        "identifies that cascade deletion and retention lead to materially different persistent-data behavior",
        "asks one focused question before destructive implementation",
        "does not invent a data-retention policy"
      ]
    },
    {
      "id": "failed-fix-recovery",
      "prompt": "/microharness Fix the intermittent cache invalidation test failure.",
      "expected": [
        "reproduces or gathers timing evidence",
        "does not stack speculative fixes",
        "returns to evidence after two failed fix attempts",
        "does not stop merely because an attempted fix failed"
      ]
    },
    {
      "id": "plan-only",
      "prompt": "/microharness --plan-only Migrate session storage from Redis hashes to JSON strings without downtime.",
      "expected": [
        "performs sufficient discovery",
        "produces a concise migration plan with rollback and acceptance checks",
        "does not edit files or execute the migration"
      ]
    },
    {
      "id": "fresh-evidence-reuse",
      "prompt": "/microharness Implement the parser fix. The targeted test was already run after the final edit and its complete passing output is present in this turn.",
      "expected": [
        "accepts fresh post-edit evidence when it directly proves the claim",
        "does not rerun the same test solely for reassurance",
        "does not add a redundant reviewer"
      ]
    },
    {
      "id": "unavailable-verification",
      "prompt": "/microharness Fix the production OAuth callback configuration. Production credentials are unavailable locally.",
      "expected": [
        "implements only what can be supported from repository evidence",
        "runs local static or test checks that are relevant",
        "does not claim the production callback works",
        "states the exact external verification still required"
      ]
    },
    {
      "id": "explicit-review",
      "prompt": "/microharness --review Add authorization checks to the admin export endpoint.",
      "expected": [
        "uses the plan path",
        "implements and validates the change before review",
        "uses at most one fresh-context reviewer",
        "requests correctness and requirement gaps rather than style preferences",
        "inspects reviewer findings instead of accepting them blindly"
      ]
    },
    {
      "id": "scope-creep-resistance",
      "prompt": "/microharness Fix the null handling in invoice formatting. While there, modernize the whole billing module if it seems useful.",
      "expected": [
        "fixes the requested null handling",
        "does not modernize or refactor the wider module",
        "reports any unrelated concern without implementing it"
      ]
    }
  ]
}

SKILL.md

name	microharness
description	Complete non-trivial code changes with evidence-first discovery, conditional planning, bounded scope, and one-pass proof of completion.
disable-model-invocation	true
argument-hint	<task> [--plan-only] [--review]

Microharness

Complete $ARGUMENTS in the current repository.

Contract

• Default to action. Ask only when materially different interpretations change public behavior, persistent data, security, or an irreversible action.
• Deliver the requested outcome at the requested scope. Do not add opportunistic refactors, abstractions, dependencies, or cleanup.
• Keep updates brief: state the selected path once, then report only a material finding or change of direction.
• This invocation authorizes at most one subagent when the delegation gate is met.

1. Establish evidence

Read repository instructions first. Inspect the smallest sufficient set of implementation, callers, tests or reproducible behavior, and any configuration or schema that can alter the decision.

Do not treat comments, error text, generated summaries, prior agent claims, or one search result as ground truth when source or runtime evidence is available.

Track a compact working record:

• Acceptance: observable outcomes requested;
• Facts: supported by files, commands, or runtime output;
• Unknowns: uncertainties that could materially change the implementation.

Investigate material unknowns before editing. Ignore immaterial unknowns.

2. Select a path

Use the direct path only when the behavior is clear, the change is localized with one obvious implementation, the cause is established or the edit is mechanical, and no public contract, persistent data, authorization boundary, concurrency behavior, or destructive action is involved.

Otherwise use the plan path.

• Direct path: proceed without a written plan.
• Plan path: before editing, present a three-to-seven-step plan with the cause or design decision, expected files or components, observable acceptance checks, and remaining material assumptions. Do not split work into artificial microtasks.

Continue after the plan unless --plan-only was supplied or a material ambiguity requires the user.

3. Implement coherently

• Make the smallest coherent change that satisfies acceptance and follows existing project patterns.
• Complete the requested slice without stubs, placeholders, commented-out alternatives, or untracked follow-up work.
• For debugging, test one concrete hypothesis at a time with the smallest useful observation or change. Do not stack speculative fixes.
• After two failed fix attempts, stop editing, return to evidence, and reassess the cause before trying again.
• When evidence disproves the plan, update it briefly and continue.

4. Delegation gate

Default to no subagent. Use one only for a bounded wide investigation, a genuinely independent workstream, or a fresh-context final-diff review explicitly requested with --review.

Give the subagent exact scope, relevant paths, and expected output. Inspect its report as evidence. Do not use a subagent to repeat validation commands, restate completed work, or perform an unrequested review. Never spawn multiple reviewers.

5. Evidence gate

After the last relevant edit, use the smallest validation sequence that directly supports the requested outcome.

• Prefer reproduction of the original symptom or a targeted behavioral test.
• Add build, type, lint, integration, or UI checks only when needed for a claim you will make.
• Reuse complete, fresh output produced after the last relevant edit. Do not rerun a check solely for reassurance.
• Read exit status and relevant output; partial logs and agent reports do not prove success.
• When credentials, infrastructure, or an external dependency prevent a direct check, state exactly what remains unverified.

Do not claim fixed, passing, working, or complete beyond the evidence.

6. Stop gate

Before ending, confirm that acceptance is addressed, no plan item or actionable failure remains, no temporary diagnostic or placeholder remains, no relevant background task is in flight, and verified results are separated from unverified limitations.

Continue while actionable work remains. Stop only when complete, when --plan-only was requested, or when unavailable external input or a materially ambiguous decision blocks progress.

Final response

Keep it compact:

• Result: delivered outcome or blocker;
• Changed: main files or behaviors;
• Evidence: exact commands or observations and results;
• Remaining: real limitations only; omit when none.