tvproductions/gzkit / .agents/skills/gz-issue-file
gz-issue-file
VerifiedUse from a consuming repository to file a gzkit defect or enhancement at tvproductions/gzkit.
gz-issue-file
Invocation
/gz-issue-file
No ID argument. gh issue create (invoked under the hood by gz issue file)
assigns the next available issue number on tvproductions/gzkit; the skill
records the assigned number into session evidence after creation.
When to use
When working inside a gzkit-consuming repository and the finding belongs to a gzkit-owned surface:
- The
gzCLI itself misbehaves (parser, dispatcher, output, exit code). - A schema under
src/gzkit/schemas/is over- or under-strict. - A validator scope (
gz validate --<scope>) misses or false-flags drift. - A ledger event semantic drifts from doctrine.
- A rule under
.gzkit/rules/**contradicts another rule or is silently skipped. - A skill or hook surface in
.gzkit/skills/or.gzkit/hooks/regresses.
For enhancements to any of the above, file with --enhancement instead of
--defect.
When NOT to use
- Defects in consumer-repo code, content, or governance — file at the
consumer's tracker via plain
gh issue create. - In-flight defects against gzkit that meet the direct-fix thresholds in
AGENTS.md§ Defect-fix routing (diff size ≤10 source lines OR ≤2 source files; single named surface; ≥3 recentfix(precedents) — fix in place withfix(<scope>): … (GHI #N)rather than filing.
Procedure
-
Preview first with
--dry-run:uv run gz issue file \ --title "<gzkit-surface description>" \ --body "<must reference gz <verb>, .gzkit/, src/gzkit/, or gzkit.<module>>" \ --defect \ --dry-run -
Confirm the provenance line and target in the dry-run output:
Filed from <owner>/<repo> running gz vX.Y.Zis the first line of the issue body (the dry-run printsTarget:/Label:/Title:above it).Target: tvproductions/gzkit.Label: defect(orenhancement).
-
File live by re-running without
--dry-run. The wrapper invokesgh issue create --repo tvproductions/gzkit --title T --body B --label Land propagatesgh's exit code on failure. -
Record the assigned issue number into the relevant brief, GHI, or commit body so downstream
(GHI #N)references resolve.
Doctrine
.gzkit/rules/gh-cli.md§ Cross-repo filing — the canonical doctrine surface this skill operationalizes..gzkit/rules/agent-failure-modes.md§ Safeguard circumvention — the failure shape this wrapper closes structurally.AGENTS.md§ Execution Rules (Operator PII) — the auto-stamped trailer composes only the repo slug and gz version; no email is ever derived.
Output Contract
Default form: plain text (one Target:/Label:/Title: line each, then
the composed body). --dry-run is the canonical preview affordance.
The wrapper has no --json flag: filing an issue is a side-effecting
operation whose canonical output is the GHI URL on stdout (gh issue create's default), not a structured payload.
Failure Modes
| Failure | Cause | Resolution |
|---|---|---|
| Exit 1, "issue body references no gzkit-owned surface" | Body lacks gz <verb>, .gzkit/, src/gzkit/, or gzkit.<module> | Edit body to name the gzkit surface; or file at the consumer's tracker if the defect is consumer-owned |
| Exit 1, "no git remote found" | Working tree is not a git repo or has no remote | Run from a real git working tree |
| Exit 2, mutually-exclusive flag conflict | Both --defect and --enhancement supplied (argparse rejects before the command body runs) | Pick one |
| Exit 2 | gh subprocess failed (auth, network, GitHub API error) | Run gh auth status; check network; re-try |
Related
- Manpage:
docs/user/manpages/issue.md - Command doc:
docs/user/manpages/issue-file.md - Operator runbook entry:
docs/user/runbook.md§ Cross-Repo Defect Filing - Governance runbook entry:
docs/governance/governance_runbook.md§ Cross-repo defect routing - Parent ADR:
docs/design/adr/foundation/ADR-0.0.23-agent-failure-mode-taxonomy/ - Source brief: GHI #316
- Sibling skill:
ghi-author— for filing GHIs at the current repo (not cross-repo)
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 |