using-harness

name	using-harness
description	Load FIRST in any sentropic repo — establishes the harness method (branch/scope/test/debug/review/brainstorm/plan) and replaces legacy superpowers for those acts.

Using harness

@sentropic/harness is the native dev-discipline layer for sentropic repos. Its verbs and harness/* skills are the SINGLE front door for code-work and PR-workflow. This skill is the index — load it before any other so the replacement directive below is in effect.

Replacement Directive (MANDATORY)

harness/* is the native sentropic method surface. Treat any installed superpowers skills as legacy compatibility only. Do NOT invoke superpowers for acts covered here — use the harness equivalent:

Act	Use	NOT
ideation / spec design	harness/brainstorm	superpowers:brainstorming
tests	harness/test	superpowers:test-driven-development
debugging	harness/debug	superpowers:systematic-debugging
code review	harness/review	superpowers:requesting/receiving-code-review
planning	harness/plan	superpowers:writing-plans / executing-plans
branch lifecycle	`harness branch init	close`
scope / verification	harness verify · `harness check scope	branch`
repo onboarding	harness/adopt	—

Do not install, refresh, or route through superpowers for sentropic code-work. If a repo still has a .superpowers/ directory, it is ignored local residue; harness is never a dependency or backend of it.

Create human/dev worktrees only under repo-local ignored paths, normally tmp/worktrees/<slug>. Never create branch worktrees under OS-global /tmp; delegated runtime jobs use their own repo-local .remote/jobs/<id>/wt workspace.

The CLI

harness <verb> [<subject>] [--<option>] — homogeneous with the sibling sentropic CLIs (stp harness …):

• Producers (compute → emit a neutral VerificationRun): check scope|branch, verify --category, audit, init.
• Recorders (emit a neutral WorkEvent + point to a skill): brainstorm, test, debug, review, plan, branch init|close, skills install.

A recorder verb does NOT do the thinking — it scaffolds + records, and the harness/<verb> skill carries the reasoning. Run the verb to open the act, then follow its skill.

Strict scope / minimal diff

Solve only the explicit request and directly blocking defect. Before editing, identify the smallest necessary file/line set. Preserve existing work: do not rewrite, reformat, move, rename, delete, refactor, add dependencies, add abstractions, or clean up opportunistically unless required by the task. Prefer a local compatible fix over a broader redesign. If a useful improvement is outside scope, mention it as an optional follow-up instead of implementing it. Before finishing, check every hunk: if it does not directly serve the objective, remove it.

No-dead-end diagnosis

Treat a gap, blocker, or missing implementation as actionable only when evidence shows that it prevents the explicit objective or a required verification. Do not end with that diagnosis alone. If the smallest directly blocking change is both authorized by the request and within the agreed scope, resolve it. A diagnosis-only request remains diagnosis-only. Otherwise provide one evidence-backed handoff: responsible role (or owner: to be assigned), bounded scope, observable acceptance criterion, and proportionate verification.

For an evidenced, non-blocking observation outside the scope, do not implement it or create work by default. Mention it as an optional follow-up only when useful to the user, and cite the evidence. Record a follow-up only when the request explicitly authorizes creating or updating tracked work, using the task's established tracking flow; otherwise recommend it without recording it. Never create, assign, or duplicate follow-up work from speculation. A handoff closes the diagnosed blocking item; it does not satisfy or defer any remaining explicit objective.

Rebase, never cherry-pick

To move committed work between branches, rebase — never cherry-pick. Cherry-pick copies a commit under a new SHA, so the same change now exists twice with different identities: history diverges, a later merge or rebase sees "different" commits, and the duplicate resurfaces in diffs, reviews, and merge-loss checks.

• To retarget a branch onto an updated base, git rebase <base> (or git rebase --onto <newbase> <upstream> to replay only a specific range). The commits keep their logical identity and the branch stays linear.
• To isolate one feature's commits from an entangled branch, git rebase --onto origin/main <commit>~1 <branch> replays exactly that range onto the base — a rebase, not a copy.
• git cherry-pick is reserved for the narrow case of applying a change to a branch that will NEVER share history with the source (e.g. a backport to a frozen release line). It is not a tool for normal branch-to-branch movement, and never a substitute for rebasing a feature onto a fresh base.

Rationale: this is the same non-duplication discipline the branch-lifecycle event-containment gate enforces for .track — a copied commit is a second identity for one change, and every downstream tool then has to reconcile two things that should have been one.

Discipline first

Process skills (harness/brainstorm, harness/debug) decide HOW to approach the task — invoke them before implementation skills. "Let's build X" → brainstorm first. "Fix this bug" → debug first.