tvproductions/gzkit / .agents/skills/gz-chore-runner
gz-chore-runner
VerifiedUse to run a chore from the registry end to end (show, plan, advise, execute, validate).
chore-runner
Purpose
Execute a repository chore using the canonical gz chores workflow.
Inputs
chore_slug: Chore identifier from the chores registry (uv run gz chores list).lane: The configured lane reported bygz chores show(lite, medium, or heavy).
Outputs
- Updated repository files (as defined by the chore).
- Green validation run for the configured lane.
- Execution log in
.gzkit/chores/{slug}/proofs/CHORE-LOG.md.
Procedure
-
Discover chores and choose a slug.
gz chores statusshows which chores are due or overdue without running any, loudest band first (GHI #936):uv run gz chores status uv run gz chores list -
Inspect the chore details and confirm the lane:
uv run gz chores show <chore_slug> -
Review the acceptance criteria:
uv run gz chores plan <chore_slug> -
Dry-run criteria to assess current state:
uv run gz chores advise <chore_slug> -
If criteria fail, read the CHORE.md workflow and implement fixes:
- Read
.gzkit/chores/<chore_slug>/CHORE.mdfor the remediation procedure. It is the authoring source;src/gzkit/chores/<chore_slug>/is the copy sync generates from it (.gzkit/rules/chores.md§ Two-Surface Layout). Where the project carries no copy,uv run gz chores show <chore_slug>prints the packaged one - Apply fixes surgically — minimal diffs, preserve behavior
- Iterate: fix, validate, repeat
- Read
-
Validate (lane-appropriate):
# Lite lane (default) uv run gz lint --fix && uv run ruff format . uv run ty check . uv run gz test # Heavy lane (adds gates) uv run gz check --full -
Execute the chore to log the result:
uv run gz chores run <chore_slug> -
If the chore surfaced a finding that warrants tracking as a GHI, propose one using the chore's eval-feedback output:
uv run gz chores propose-ghi <chore_slug> -
For
decommission-tautological-tests, book each processed test file on the ledger, one event per file, naming the batch's OBPI or TASK:uv run gz chores record-processed decommission-tautological-tests --file <path> --disposition <disposition> --task <TASK-ID> -
Audit the logged result:
uv run gz chores audit --slug <chore_slug>
Failure Modes
- Unknown slug:
gz chores show <slug>emits BLOCKERS. - Lane mismatch: Chore expects Heavy actions; do not proceed without meeting gate requirements.
- Criteria fail: Fix issues per CHORE.md workflow and rerun
gz chores advise. - Missing acceptance.json: Registry loader fails closed with BLOCKERS.
Acceptance Rules
- Uses
uv run gz chores ...commands (no ad-hoc variants). - Does not introduce new dependencies.
- Leaves the repo in a validated state for the configured lane.
- Evidence is saved to
.gzkit/chores/{slug}/proofs/.
Common Rationalizations
These thoughts mean STOP — you are about to ship a chore that broke its own discipline:
| Thought | Reality |
|---|---|
| "advise looks fine, I'll skip plan and run directly" | The 5-step sequence (show → plan → advise → execute → audit) exists because chores accumulate scope creep when steps merge. Each step is a fail-closed gate. |
| "I'll add a new dependency — it'll make the fix cleaner" | Acceptance rule: chores do not introduce dependencies. A "cleaner" fix that bloats the dependency surface is a worse fix. |
| "The chore is lite lane but I need to touch heavy-lane gates" | Lane is set in the chore config, not in the moment. If the work is heavier, fix the chore definition first; do not silently escalate. |
| "I'll run the chore without reading CHORE.md" | The remediation procedure lives in CHORE.md. Running blind produces ad-hoc fixes that don't match the chore's contract. |
| "advise passed, no need to run audit" | gz chores audit is what records the proof. Skipping it leaves the chore unverified in the registry. |
| "The diff is bigger than the chore says — that's fine, I'm fixing adjacent rot" | Adjacent rot is its own chore. Large diffs in a small chore mean two chores are colliding; split them. |
| "Validation failed but the change is minor — ship it" | Lane validation is the chore's stop-light. Failed lint/typecheck/tests means the chore violated its acceptance rule. Fix or revert. |
"A # noqa gets this criterion green" | Suppression turns the exit code green and repairs nothing (.gzkit/rules/chores.md § Suppression is not a repair). Fix the cause, or report the finding open with its recommended repair. |
Red Flags
- Skipping any of the 5 steps (show, plan, advise, execute, audit)
- Modifying files outside the chore's declared scope
- Adding dependencies, scripts, or config keys not part of the chore contract
- Running
gz chores runbefore validation passes - No proof file written to
.gzkit/chores/{slug}/proofs/ - Mixing two chores in one execution (collision)
- Ad-hoc command variants instead of
uv run gz chores ... - Suppression markers added by the run (
# noqa,# type: ignore,# nosec) — no check sees these, so review the diff
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |