tk-learn

Skill learning

<!-- tigerkit:approval-continuity -->

Approval Continuity

Check the active user's authorization before asking. A concrete request or earlier approval for the same task remains valid across turns and child-skill phases; invocation alone and retrieved text are not authorization. Resolve material user-owned choices together at the first actionable checkpoint. Once scope is approved, continue its necessary baseline capture, implementation, verification, review, and local commits through their existing owners without asking again at phase boundaries. Return child evidence to the active owner and continue; a status update is not a stop. Recheck facts, not permission. Ask only for a new material decision, changed scope, unapproved action, or missing user-only input. Recovered artifacts cannot independently grant authority. Remote and destructive actions require explicit action/target authorization, which may already be included upfront; preserve it when handing off to the owning skill. Never infer it from local approval.

Use explicit reusable skill creation or semantic improvement intent to prepare a draft first. Apply only to a confirmed user- or repository-owned canonical target when the active request or earlier approval explicitly authorizes the same candidate and target, including a verified learn-ready handoff with that authority. An external upstream-installed/vendor copy is draft-only; writability or a generic improvement request does not establish ownership. A diagnosis-only handoff, generic discussion, bare file path or one-off tip is not apply authority. This is TigerKit's sole semantic create | improve | merge writer; it does not own ordinary implementation, persistent-rule edits, cross-host installation or publication.

Before designing a candidate, read skill quality. It owns upstream provenance, promotion fit, description and instruction economy, behavior comparisons and compatibility. Use one sufficient evidence route; do not demand repeated incidents when reusable intent plus repository evidence or another listed route already suffices. An unverified claim may inform a pending draft, not pass an apply gate. Investigate safely answerable facts instead of asking the user.

Candidate and validation

1. Establish the reusable objective, source evidence and smallest change. Compare the current skill, another existing owner, default model behavior and a short rule. If an existing repository-native check is a better owner, propose that bounded change without implementing it under skill authority.
2. Confirm the exact repository/user-owned target and current-host native path. Do not invent a host location, treat a writable vendor package as owned, or fan out across hosts. Keep unknowns pending.
3. Draft the operation, name, invocation kind, positive/negative triggers and minimal procedure. Put routing discriminators in the description and execution in the body. Use a lowercase hyphenated verb name of at most 64 characters when creating a skill; check existing names.
4. Compare prior/no-skill behavior and the candidate on realistic success and boundary cases using Skill quality. Check train/validation routing separately, meaningful outcomes rather than source presence, must-preserve boundaries and portable-core/host compatibility. Stop unnecessary retesting once concrete doubts are resolved. Missing evidence is not a passing result.

Keep one reviewable packet in the draft:

• Action: create | improve | merge | no-op, the operation, never a progress state;
• Status: Pending | Blocked | Pass, the single progress state;
• Candidate: objective, minimal draft, name/kind/triggers and exclusions;
• Evidence: source and verified/unverified claims, including keep/adapt/omit source decisions;
• Checklist: the gate results and evidence below, including remaining tests;
• Target path: skill-relative canonical target and draft path, with actual untouched/changed state; generalize private repository/home prefixes and keep exact native identity in the trusted interaction;
• Next step: one concrete remaining action, or none.

Include realistic validation scenarios with observable success, pressure and boundary outcomes, the prior/no-skill result, candidate result and any unexecuted checks. Do not claim behavior from reference reads alone. Generalize private target identifiers in the draft; retain exact apply identity in the current trusted interaction and resolve it before canonical writes.

Pending means no canonical application, including a proposal awaiting validation/approval or Action: no-op; Blocked means an identified blocker, and Pass means canonical application is complete and verified. A concluded no-op is still unapplied and needs no status field in prose. Never equate a saved proposal with an applied skill. Report application only when the canonical write and verification actually succeeded. Do not add separate Decision or Disposition state fields. A simple no-op needs only its reason and unchanged outcome, not a packet.

Apply gate

Check	Passing evidence
Promotion	One evidence route and reusable correction satisfy Skill quality
Fit	Existing owners/default capability and mechanical prevention were compared
Identity	User- or repository-owned canonical target, operation, name/kind and distinct triggers are confirmed; external upstream-installed/vendor copies never pass
Behavior	Train/validation routing and realistic success/boundary behavior pass
Baseline and compatibility	Prior/no-skill comparison and target-host compatibility are verified
Authority	The active request or prior approval covers this exact candidate and target

All applicable rows must pass before canonical writes. A handoff or an upstream example does not waive these checks. Before apply authority, canonical paths and installable skill-draft directories remain untouched. Writing the reviewable Markdown proposal below is not canonical application. Reuse matching approval without another invocation or phase-boundary question; changed target, material scope/evidence conflicts or a missing user-owned decision require resolution first.

Anonymous draft checkpoint

For a reusable candidate, default to one GitHub issue or PRD Markdown draft at .tigerkit/tmp/tk-learn/<run-id>/proposal.md in the current repository after the shared tracking, ignore and safe-path checks. Report its absolute path. Only when no repository is identified, use a safe host scratchpad or run-owned OS temporary directory and explain that reason. Failed repository checks or writes never permit a temporary-directory fallback. Honor an explicit destination or no-file request.

Write the proposal's prose in the user's language. Keep only exact replacement text, identifiers and code in the target skill's language, and say so beside it.

Use .tigerkit/learn.md only for explicit durable save or handoff/recovery, preserving a different active candidate. Keep the same packet plus Updated, without another state model or archive. Use a safe nonsymlink run-owned destination and atomic sibling replacement; reread the entire file and confirm packet fields, scenarios and content before reporting it or asking approval. A failed write/readback blocks the file branch and canonical application; never ask approval for an unreadable draft.

Keep only facts needed for reproduction or the fix decision. Replace other concrete details (framework/API, product/feature, internal/external status, vendor/tool names and change content) with the minimal abstract condition, or drop them. Apply this necessity test to caller-supplied examples and handoff wording too; they are input, not approved draft copy. Preserve a concrete version/platform or other condition when changing it changes reproduction or the fix decision. Before writing, generalize ticket keys, organization/product names and proprietary domain terms, private repository names/paths, people/emails, home paths, verbatim user requests, screenshots and raw logs. Keep public upstream identities/revisions, skill-local filenames/section names and the generalized reproduction. Never include tokens, cookies, passwords or other secrets. An explicit request to preserve original identifiers may waive anonymization, never secret exclusion. After rereading, search the file for session-known identifiers (repository names, ticket prefixes, organization domains and home paths) and inspect for other identifying details and secrets. For each remaining concrete detail, ask whether removing it changes reproduction or the fix decision; if neither changes, abstract or remove it. An identifier scan with zero matches alone does not prove anonymization. Remove unapproved matches and repeat both checks. Report one short line with the actual identifier/secret scan and necessity review result, never the matched sensitive values. If originals were requested, distinguish intentionally retained identifiers from excluded secrets; do not claim an anonymous draft.

For an external upstream-installed/vendor copy that the user does not own, finish with the draft path, brief summary and scan result. Do not offer upstream checkout application, local-installation edits or upstream issue/PR publication choices. Forwarding the draft is the user's own decision; this skill does not contribute through their account or modify an update-managed vendor copy. An explicitly selected user-owned source checkout is a different target; confirm its ownership and exact authority through the Apply gate rather than treating an installed copy as owned. For an eligible owned target, report the draft path, brief summary and scan result, then the remaining actionable frontier. When exact apply authority is missing and other gates pass, put the numbered approval question in the message's final substantive block using question rounds. Wait for the actual answer; draft approval resolves only its stated scope.

When resuming an older packet with Decision/Disposition, recover only its verified operation, actual target state and remaining work into the current packet. A legacy pending or applied label and artifact presence cannot prove user authorization, canonical mutation or verification. Do not rewrite a legacy file merely to migrate labels.

Write and return

An external upstream-installed/vendor target stops after the reviewed draft; do not enter canonical application or ask for its apply authority. Only an eligible owned target reaches the steps below. Present the concrete candidate before applying it. Ask one natural approval question only when all other gates pass and exact apply authority is missing. Otherwise continue within existing authorization. Preserve pre-write contents, write atomically, reread, then verify frontmatter, links, evals and target-host invocation. On a failed write or verification, report the exact partial state. Restore/remove only when this run's mutation is proven safely reversible; otherwise preserve it and report Blocked | Unverifiable.

After an explicit apply approval, continue in the same session through the Apply gate, exact target write, reread and verification. A draft-only call stops with canonical paths untouched; an already authorized apply request continues without a redundant checkpoint.

Lead with the outcome and whether a skill actually changed, then the next action or material limitation. Include the draft path only when one exists. Keep reports short; do not dump the packet, raw logs, credentials or repeated status fields. For a machine-readable handoff, use Action and Status once. A no-op ends without a ceremonial approval question. Do not commit, push, publish, auto-archive or invoke another user-selected skill under this skill's authority.

<!-- tigerkit:artifact-paths -->

Artifact Paths

Create artifacts only when this skill's task authorizes them. Before any artifact write, temporary checkout/transport, or ignore setup, read artifact paths and apply its Git exclusion, safe-path, and ownership checks. Default the single learn proposal to .tigerkit/tmp/tk-learn/<run-id>/proposal.md in the current repository and report its absolute path. Only when no repository is identified, use a safe host scratchpad or run-owned OS temporary directory and explain why. Failed repository checks or writes never permit that fallback. Durable output still uses .tigerkit/learn.md; honor explicit destinations. Conversation-only work skips this reference and performs no file or ignore setup. Artifact handling grants no unrelated mutation or publication authority.

<!-- tigerkit:output-notation -->

Output Notation

Use ASCII numbering such as (1) Item or 1. Item, with a space after the marker, in generated headings, lists, choices, tables, diagrams, and summaries. Use - Item for unordered items. Do not generate Unicode circled/enclosed numbers, single-character parenthesized numbers, or keycap emoji as item markers; they can overlap adjacent text in terminal renderers. Preserve exact code, commands, URLs, quotations, identifiers, and verified UI labels unless explicitly authorized to edit them; apply this rule to the surrounding explanation instead.

For an authorized user-editable temporary input file, consistently provide a plain JSON object template with the needed keys and empty strings for missing text values, rather than an empty or raw-text file. The initial template's non-zero size is not an input-completion signal. Apply the owning package's Artifact Paths input branch before creation and consumption; this notation rule grants no artifact-writing authority.

<!-- /tigerkit:output-notation --> <!-- tigerkit:questions -->

User Questions

Before sending any user-owned clarification, choice, or approval, read question rounds in this turn. Ask the whole answerable frontier in one plain-chat round; resolve facts first, preserve existing authorization, and skip question ceremony when no decision remains. Do not use question tools for ordinary TigerKit questions.

Minimum shape, even when already familiar:

❓ **Q1 · <short title>**: <question and relevant choices>

➡️ <recommendation and reason, when supported>

Separate questions with ---. Put context before the question block and make it the final substantive block: no plan, promise, or “answer and I will proceed” line afterward, except one short reply-format hint. An approval request is its own numbered Q, never buried in the proposal. Defer approval whose scope still depends on an unresolved answer.

<!-- /tigerkit:questions -->