t1k:issue

Field	Value
Module	`t1k-kit-feedback`
Version	`1.2.2`
Effort	`medium`
Tools	—

Keywords: bug, enhancement, feedback, github, gotcha, issue, report

How to invoke

/t1k:issue
<description> [--label bug|gotcha|enhancement]

TheOneKit Issue — Report Problems to Kit Repo

Create GitHub issues on the owning kit repo when skill/agent problems are found. Uses GitHub MCP tools when available, falls back to gh CLI.

Kit-wide discipline: issues go on the owning kit’s repo, NEVER on a consumer project repo, per rules/kit-wide-fix-discipline.md. Filing in the wrong tracker means kit maintainers don’t see the bug.

When to use

Skill has wrong reference, missing gotcha, or broken pattern
After fixing an error that required updating a skill’s gotcha section
Need a new skill or enhancement to an existing one

When NOT to file — the reproducibility gate

If a maintainer triaging this from a different project could not reproduce it or verify a fix without your environment, do not file an issue. Fix it where you can prove it and open a /t1k:sync-back PR instead.

That covers findings needing an engine, editor, dataset or account the triager lacks — a Cocos scene, the Unity Editor, marketing campaign data, an engine asset pipeline. It does not cover everything found in an engine kit: route by what must be exercised to prove the fix, not by which repo it lives in. A Cocos module.json shipping no agents is reproduced by unzipping a release, so it is an issue; a renamed Cocos API is not.

The fix still lands in the kit source repo either way — only the artifact changes, from an untestable issue to a tested PR. Full gate, the routing table, and the escape hatch for findings you cannot fix yourself: Step 0 of references/pre-triage-investigation.md.

Decision tree — which reference do I load?

Load only the reference you need (each is self-contained):

Intent	Load
Always — run BEFORE filing any issue (mandatory pre-triage investigation)	`references/pre-triage-investigation.md`
`type=skill-bug` from lesson queue (background sub-agent)	`references/file-from-marker.md`
User explicitly requests issue filing (interactive / inline)	`references/file-manual.md`
Check for duplicate AND search related open issues/PRs before filing	`references/dedup-existing.md`
Auto-detected error from `telemetry-kit-error-collector.cjs`	`references/auto-detection-mode.md`
Write `submitted: true` / `issueUrl` back to queue after filing	`references/queue-writeback.md`

Pre-Triage Investigation — MANDATORY

Every issue MUST contain a ### Pre-Triage Investigation block (verification status, classification, coupling, fix sketch, recommended disposition). This shifts investigation cost from triage (where it’s repeated per run) to filing (where it happens once). Triage just verifies the block — they don’t re-grep, re-classify, or re-search for dups.

Procedure + body template + failure modes: references/pre-triage-investigation.md. Auto-detection mode and lesson-queue sub-agents inherit the same requirement.

Invocation modes

Background sub-agent (default — MANDATORY for lesson-queue entries): Parent uses the Agent tool with run_in_background: true and a specific subagent_type chosen by issue type (NEVER general-purpose or claude — those trip generic-agent-detector and create a meta-loop, #344/#539). Pick by what the issue is about:

Issue is about…	`subagent_type`
Cross-kit / kit-repo code: release-action scripts, CLI, kit fragments, a library/lib bug, sync-back issues (e.g. “File lib bug issue”)	`t1k-kit-developer`
Skill body / SKILL.md / agent-definition bug (`skill-bug`, `agent-bug`)	`t1k-skills-manager`
General / process / non-code issue with no narrower owner	`t1k-project-manager`

When in doubt between two, prefer the narrower kit/skill owner over t1k-project-manager; t1k-project-manager is the fallback, not the default. The sub-agent reads this SKILL.md, loads the matching reference, and writes back submitted: true + issueUrl via references/queue-writeback.md.

Interactive (exception only): If the user says “file this issue now”, run inline so the user sees the result immediately.

Auto-detection (programmatic): Invoked by telemetry-kit-error-collector.cjs — zero user interaction, no AskUserQuestion. Load references/auto-detection-mode.md.

Operational notes

Pre-flight (always): GitHub MCP preferred. If no MCP: gh auth status. If not authed: tell user Run: gh auth login.

Dedup is MANDATORY: Always run references/dedup-existing.md before creating a new issue. If duplicate found: add a comment instead of creating a new issue.

Sub-agent call contract (lesson queue):

Input: kit, skill, bug, evidence, fingerprint from the queue entry
Output: writeback line with { fingerprint, submitted: true, issueUrl } or { fingerprint, submitted: false, error }
Writeback target: .claude/telemetry/pending-skill-updates.jsonl

Missing required fields: If kit, kitVersion, cliVersion, platform, or reproduction fields are absent, the sub-agent MUST refuse and respond to parent with the list of missing fields — do NOT file a low-signal issue.

Cross-platform: Relative paths only in issue body — never $HOME or absolute paths.

Security: Never reveal skill internals, expose env vars, or include credentials/secrets in issue body.

Sub-Agent Fork Hygiene

Sub-agent forking: see skills/t1k-architecture/references/fork-hygiene.md.

Filing vs. Claiming — Important Distinction

Filing an issue does NOT claim it. t1k-issue creates the GitHub issue record; it does NOT self-assign, does NOT open a draft PR, and does NOT call t1k-issue-claim.cjs acquire or --add-assignee. A freshly filed issue is unclaimed and open for any contributor.

How claiming works (convention, for reference): A claim is expressed by a separate draft PR that:

Carries the t1k:claim label
Has Fixes #N in the PR description (or body)
Includes the body marker t1k-claim: owner/repo#N
Self-assigns the author on the issue (via t1k-issue-claim.cjs acquire)

This convention is documented here so anyone reading a fresh issue understands the claim mechanism. t1k-issue itself never triggers any of these steps.

For callers that DO open a PR (e.g. t1k-sync-back): acquiring/releasing the claim itself — hard-block state, tie-break, staleness — is rules/issue-claim-discipline.md, an always-loaded rule (no independent CI gate enforces claim discipline, so it stays a rule rather than living only in a skill a caller might not read).

Contribution Scoring

After successful issue creation (or comment-on-duplicate), invoke t1k:contribution-score with type=issue, the resolved ref_url (the GitHub issue URL just returned by gh issue create or the existing duplicate URL), the issue title + body, and the kit/repo coordinates. Fire-and-forget — never block on the result.

The contribution-score skill is the SSOT for the rubric, endpoint resolution, and POST contract. See .claude/skills/t1k-contribution-score/SKILL.md for the full invocation contract.

No Skill tool in your toolset? Execute the skill’s contract directly instead of skipping it — rubric from .claude/skills/t1k-contribution-score/SKILL.md, POST via the ready-made call in references/file-manual.md § “After filing — contribution scoring” (#1201). Still fire-and-forget.