show-logic

name	show-logic
description	Use to show the decision trail for the current branch — what was decided, why, with what perceived confidence, and on what evidence — as a reviewable table plus decision-quality notes. Invoke as /show-logic [branch] [--pr]. Collects rows across parallel worktrees, validates evidence against the diff, flags conflicts and problematic choices, and reconstructs a best-effort trail (clearly marked) when tracking was off. Use when the user asks to see or audit the rationale/logic/decisions behind a branch or PR, or to add it to a PR.
argument-hint	[branch] [--pr]
user-invocable	true
license	Apache-2.0

show-logic

Shows the decision trail for a branch as a reviewable table. Default output is the rendered table in the terminal; --pr also writes it into the PR description. Safe to run on any branch, including ones that predate tracking.

When a branch is named, every step targets that branch — its commits, its diff, its rows — regardless of which branch is currently checked out. So /show-logic other-feature from main reports that feature's trail, not main's. If the name resolves to no ref, the helpers stop with an error rather than quietly falling back to the current checkout.

All helper scripts live in .agents/skills/logic-core/scripts/.

Procedure

1. Collect

bash .agents/skills/logic-core/scripts/collect.sh [branch] > /tmp/logic-rows.json

Returns a normalized JSON array of every row for the branch, merged across worktrees and backends, sorted by time. Note the counts: total rows, and how many are unenriched stubs (.stub == true).

2. Detect the tracking state — this decides everything below

• Tracked, with rows → go to step 3 with the real trail.
• Tracked but zero rows (resolve-branch.sh says on, collect is empty): call this out as a compliance failure, not a quiet reconstruction — usually the hook didn't fire. Then reconstruct so the user still sees something, clearly labeled.
• Off entirely (resolve-branch.sh says off, no rows): state plainly up front that tracking was not enabled for this branch, so what follows is a reconstruction from artifacts, not recorded decisions. Then reconstruct.
• Partial (rows exist but the branch predates them): show the real rows and reconstruct only the untracked span. Never blend real and inferred rows silently.

Check state with:

bash .agents/skills/logic-core/scripts/resolve-branch.sh --json

3. Validate evidence resolution and coverage

bash .agents/skills/logic-core/scripts/audit.sh [branch]

Reports rows whose evidence doesn't resolve and changed files no row explains. Surface these as gaps; do not silently drop unresolved rows. This is a mechanical check: a resolving commit or path anchors a decision but does not, by itself, prove that the choice was sound.

4. Reconstruct (only when needed, per step 2)

bash .agents/skills/logic-core/scripts/reconstruct.sh [branch] > /tmp/logic-recon.json

This emits raw material only (commits + trailers, the diff, beads task issues, PR body/comments) — it writes nothing. Turn it into inferred rows yourself:

• Reliability order: commit messages/trailers > diff grouped into units > beads task issues > PR text.
• Every inferred row is marked actor=inferred, and its why is phrased as a hypothesis ("likely because …"), never stated as fact. Its perceived decision confidence is unknown; never infer the original actor's certainty.
• Put a warning banner above any reconstructed table.
• Reconstruction is a view, not a backfill — never write inferred rows into beads. If the user wants to keep one, that is an explicit, separate follow-up where they confirm it and it's logged with them as the actor.

5. Conflicts across parallel worktrees

bash .agents/skills/logic-core/scripts/conflicts.sh [branch]

Returns mechanical pre-filters: tier 1 (a file touched by rows from more than one worktree) and tier 2 (real textual conflicts from git merge-tree between the worktree branches). Read the paired rows and make the tier-3 call yourself: is this a genuine semantic contradiction (e.g. two worktrees chose opposite approaches for the same view)? Write a one-line tension note for each real one. A clean result means "none detected", not "none exist" — say so.

6. Assess decision quality

Audit the choices, not every line of generated code. Use the diff, tests, benchmarks, requirements, and other artifacts as evidence. Review only load-bearing rows: architecture, security, data integrity, performance, irreversible choices, and decisions already marked low, INCONCLUSIVE, or open.

For each material choice, ask:

• What option was selected over what plausible alternative?
• What constraint, invariant, or assumption makes it valid?
• What boundary case or counterexample could break it?
• Does the evidence support the reason, or merely anchor where code exists?
• Does the decision need an owner ruling?

Confidence is the actor's perception, not a verdict. Pay special attention to high-confidence rows with weak or anchor-only evidence, low-confidence load-bearing choices, unresolved assumptions, contradictory rows, and confidence that did not change after counterevidence.

Prepare a separate ## Decision quality section after the trail. Use concise notes, each naming the row or decision, its recorded confidence, the potentially problematic area, and any owner ruling needed. Use supported, assumption-dependent, contradicted, or needs-owner-ruling as assessment labels. If no material concerns are detected, say so; do not manufacture notes.

This section is an assessment view, not stored history. If the owner rules on an open item, record that ruling as a new append-only row with track-logic.

7. Render

cat /tmp/logic-rows.json | bash .agents/skills/logic-core/scripts/render.sh --title "Decision trail — <branch>"

One Markdown table per stream (worktree), the current checkout first, with a confidence column and stubs flagged. Follow it with conflict findings, evidence gaps, and the separate Decision quality notes. If you reconstructed, keep inferred rows in a separate, banner-headed section.

8. Cross-model review — before any outward push

Spawn a subagent on a different model family from the one that did the work (self-review does not count; if no other family is available, say so and note the review is same-family). It reads the trail, diff, and Decision quality section. Have it pressure-test the closest alternative, controlling assumptions, boundary cases, confidence/evidence mismatches, verification claims, and risky choices. End with an Attention section that leads with the reviewer's model on its own line, then the flags. No flags is valid; the model name is not optional.

This review is mandatory whenever the trail contains inferred rows or you are about to push to a PR; best-effort otherwise.

9. Optional: push to the PR

cat /tmp/logic-report.md | bash .agents/skills/logic-core/scripts/pr-push.sh [branch]

Assemble /tmp/logic-report.md from the rendered trail, evidence and conflict findings, Decision quality notes, and Attention section. The helper writes the complete report into the PR description between stable markers, so re-running replaces the section instead of stacking copies. If the trail includes inferred rows, keep the reconstruction warning in the pushed text.

10. Housekeeping

Offer to tidy rows whose branch was deleted unmerged:

bash .agents/skills/logic-core/scripts/gc.sh          # dry run, lists candidates
bash .agents/skills/logic-core/scripts/gc.sh --apply  # deletes them

Closing offer

If tracking was off or partial, end by offering to turn it on (/toggle-track-logic on) so the rest of the branch gets a real trail.