Skip to content

michael-denyer/pstack-claude / plugins/pstack/skills/show-me-your-work

show-me-your-work

Verified

Keep a reviewable decision trail for long-running or unattended work: a TSV log with one row per decision (what, why, evidence, result). Local by default; commit it when a reviewer needs the trail to trust the result. Use for /show-me-your-work, autonomous or multi-phase runs, or work a human reviews after stepping away.

FileKindSize
SKILL.mdskill md7.0 KB
references/decision-log-template.tsvother38 B
scripts/log.shexecutablescript2.2 KB

scripts/log.sh

View on GitHub
#!/usr/bin/env bash
# Append a well-formed row to a show-me-your-work decision log (TSV).
# Usage: log.sh <logfile> <phase> <decision> <why> <evidence> <result>
set -euo pipefail

if [ "$#" -ne 6 ]; then
	printf 'usage: log.sh <logfile> <phase> <decision> <why> <evidence> <result>\n' >&2
	exit 1
fi

logfile="$1"
shift

logdir="$(dirname "$logfile")"
if [ -n "$logdir" ] && [ "$logdir" != "." ] && [ ! -d "$logdir" ]; then
	mkdir -p "$logdir"
fi

# Use `>>` here, never `>`. A network mount can fail this test for a log
# that exists. Then the cost is one stray header line, not the rows.
if [ ! -s "$logfile" ]; then
	printf 'ts\tphase\tdecision\twhy\tevidence\tresult\n' >> "$logfile"
fi

ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
# Strip tabs/newlines/CR so cells stay on one line, and prefix any cell
# whose first char a spreadsheet would parse as a formula (=, +, -, @)
# or a TSV reader as an opening field quote (") with a single quote.
# The skill expects this log to be read in
# spreadsheets, so attacker-controlled evidence (PR titles, filenames,
# generated text) must not become formula execution when a reviewer
# opens the file.
clean() {
	local v
	v=$(printf '%s' "$1" | tr '\t\n\r' '   ')
	case "$v" in
		=*|+*|-*|@*|\"*) printf "'%s" "$v" ;;
		*) printf '%s' "$v" ;;
	esac
}
# A shell printf goes through stdio, which hands a row longer than its buffer
# to the kernel in pieces that parallel writers interleave.
# binmode drops the :utf8 layer PERL_UNICODE adds. syswrite refuses it on
# STDOUT, and on STDIN it decodes the row, which corrupts non-ASCII bytes.
# A short write sets no $!, so it reports its byte counts instead.
printf -v row '%s\t%s\t%s\t%s\t%s\t%s\n' \
	"$ts" "$(clean "$1")" "$(clean "$2")" "$(clean "$3")" "$(clean "$4")" "$(clean "$5")"
# perl runs once before it gets the row. A perl that is missing, a shim that
# fails, or one PERL5OPT breaks would otherwise take the row with it.
if [ "$(perl -e 'print "ok"' 2>/dev/null </dev/null)" = ok ]; then
	printf '%s' "$row" |
		perl -e 'binmode STDIN; binmode STDOUT; local $/; $_ = <STDIN>;
			my $n = syswrite(STDOUT, $_) // die "log.sh: $!\n";
			$n == length or die "log.sh: short write, appended $n of ", length, " bytes of the row\n"' \
			>> "$logfile"
else
	printf '%s' "$row" >> "$logfile"
fi
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall