Draft Issue

Use this skill when the user asks you to draft, write, or revise a GitHub issue.

This skill is for issue drafting only. Do not use it for implementation plans, PR summaries, or post-implementation reports.

Default Structure

Write the issue in the same language the user is using. Use these four sections, in this order:

## Context

<Current state: what exists today, what the user or system is doing, and any relevant background.>

## Problem

<The limitation, pain point, bug, or gap that motivates this issue.
Be specific: what breaks, what is missing, or what is confusing.>

## Goals

- <What this issue should achieve, from the user's or system's perspective.>
- <Add one bullet per distinct goal. Keep goals high-level, not implementation steps.>

## Acceptance Criteria

- <A testable or user-observable outcome that must be true when this issue is resolved.>
- <Add one bullet per criterion.>

Writing Rules

• Keep each section short and direct. Omit filler sentences.
• Context describes current reality, not the desired future state.
• Problem explains why the current reality is insufficient. One paragraph is usually enough.
• Goals are outcome-oriented, not task lists. Avoid "implement X"; prefer "user can do Y".
• Acceptance Criteria must be verifiable. Prefer observable behavior over internal implementation details.
• Do not add an Implementation Plan, Validation Commands, or Motivation section unless the user explicitly asks.
• Do not add a title unless asked; the user typically sets the issue title in GitHub.

Quality Checklist

Before returning the draft, check:

• All four sections are present: Context, Problem, Goals, Acceptance Criteria.
• Context and Problem are distinct: Context = current state, Problem = why it is insufficient.
• Goals describe outcomes, not implementation steps.
• Every acceptance criterion is testable or user-observable.
• The draft is concise — no padding, no repeated content across sections.

Quantified Milestone

Use this skill when the user asks for a milestone, next goal, handoff goal, work package, experiment goal, or asks whether a goal is clear enough for an AI or human to execute.

This skill is not a rigid template. The core rule is:

Turn important adjectives into measurable completion criteria.

Agents often write milestones that sound useful but cannot be judged, such as "improve quality", "make it stable", "run enough tests", "build a usable first version", or "validate the design". A quantified milestone defines what "done" means with numbers, thresholds, comparison targets, explicit coverage, or pass/fail checks.

When To Apply

Apply this skill whenever a milestone includes vague words such as:

• better, stronger, improved
• enough, sufficient, usable, complete
• larger, smaller, faster, slower
• stable, reliable, robust
• high quality, good, acceptable
• validate, test, evaluate, compare
• production ready, reviewable, releasable

Do not force every milestone into the same headings. Preserve the user's natural structure when possible, but add measurable criteria where the goal would otherwise be ambiguous.

Quantification Checklist

For each important goal, ask whether at least one of these is specified:

• Count: records, cases, screens, files, samples, tests, commits, runs.
• Coverage: categories, sources, platforms, modes, user flows, edge cases.
• Ratio: pass rate, completion rate, error rate, coverage rate, accuracy.
• Threshold: minimum acceptable value or maximum allowed value.
• Comparison: baseline artifact, previous version, current production path, known-good behavior, or fixed reference implementation.
• Budget: time, memory, file size, latency, CPU, cost, token usage.
• Failure handling: what to report and commit if the target is not reached.
• Artifacts: exact output files, reports, manifests, logs, screenshots, test results, or pull requests that prove completion.

Rewrite Examples

Prefer concrete criteria over vague direction:

Improve the onboarding flow.

Becomes:

Update the onboarding flow so a new user can complete account setup, create one
project, and reach the first usable workspace screen on desktop and mobile.
Validate with one automated happy-path test and two screenshots: mobile narrow
and desktop wide.

Make the UI stable.

Becomes:

The target flow completes 20 consecutive runs on desktop and mobile viewports
with no severe console errors, no overlapping controls in screenshots, and no
failed interaction checkpoint.

Write better docs.

Becomes:

Create or update the docs page so it defines the feature, lists the supported
states, includes one minimal example, links to the relevant task or spec, and
removes any outdated behavior claims from the old page.

Engineering Milestones

For implementation work, quantify:

• supported platforms or modes
• required user flows
• exact tests or evidence runs
• failure states that must be handled
• performance, size, or cost limits when relevant
• migration, compatibility, or rollback requirements

Avoid claiming "done" because code exists. Completion requires evidence that the behavior works under the stated conditions.

Product And Documentation Milestones

For product or documentation work, quantify:

• what a user can do after the change
• which concepts, states, or terms must be defined
• which pages, sections, or examples must be updated
• which outdated descriptions must be removed
• which acceptance criteria can be checked by a human reviewer
• which specs, tasks, or plans must be linked as supporting context

Keep product goals outcome-oriented. Avoid turning them into implementation task lists unless the user explicitly asks for a delivery plan.

Research And Evaluation Milestones

For experiments, do not require success when the outcome is genuinely unknown. Instead, quantify the experiment and require a useful conclusion:

Run at least N trials under fixed settings. If the target is not met, commit the
report and state the leading hypothesis for why the experiment failed.

Good research milestones include:

• a fixed baseline
• fixed settings shared by baseline and candidate
• minimum sample size
• success threshold
• negative-result reporting requirement
• required artifact paths

Good Final Check

The milestone is ready when another agent or human can answer these questions without reading the original chat:

• What does done mean?
• How will it be verified?
• Where will the proof live?
• What baseline or current behavior is it compared against?
• What happens if the target is not reached?
• What is explicitly out of scope?

If any answer is missing, tighten the milestone before treating it as ready.

Task Brief

Use this skill when the user asks for a plan, task brief, implementation brief, execution plan, or when a GitHub issue or product request needs to become an actionable task document.

This skill is for execution-ready task planning. It is distinct from:

• draft-issue: defines the need, problem, goals, and acceptance criteria.
• task-lifecycle: moves task files through backlog, doing, done, and trash.

Persistence Rule

When a task brief should be saved, place it under docs/tasks/backlog/ unless the user explicitly says the work is already in progress or complete.

Use a timestamped filename:

YYYY-MM-DD-HH-mm-<short-kebab-title>.md

Append a timezone suffix when useful or already established by the repository:

2026-06-11-14-30-+08-add-user-skills.md

Default Structure

Write the task brief in English using these sections, in this order:

# <Short Task Title>

## Background

<Plain background text, or optional subsections when they help.>

### Context

<Optional: current state and relevant existing behavior.>

### Problem

<Optional: limitation, pain point, bug, or gap.>

### Motivation

<Optional: why the change is valuable.>

## Goals

- <Outcome-oriented goal 1>
- <Outcome-oriented goal 2>

## Execution Plan

1. <Phase or step 1>
2. <Phase or step 2>
3. <Phase or step 3>

## Acceptance Criteria

- <Testable and user-observable outcome 1>
- <Testable and user-observable outcome 2>

## Validation Commands

- `<command 1>`
- `<command 2>`

Background Rules

• Context, Problem, and Motivation are optional subsections.
• Use only the subsections that fit the request size and type.
• For small or obvious changes, write direct prose under Background without subsections.
• For larger or ambiguous changes, prefer the optional subsections to separate current state, pain points, and value.

Writing Rules

• Write task briefs in English unless the user explicitly asks for another language.
• Keep the brief execution-oriented, not product-marketing-oriented.
• Keep display names and stable storage identities separate when defining extensible configuration systems.
• Include validation commands as their own section, not inside acceptance criteria.
• Make acceptance criteria testable and user-observable where possible.
• Mention specs map updates when the change affects user-visible behavior or a cross-cutting technical contract.
• Mention task lifecycle placement when saving the brief, such as docs/tasks/backlog/ for not-yet-started work.
• Avoid implementation trivia, but include enough phased detail that another agent or human can execute the work.

Quality Checklist

Before returning or saving the task brief, check:

• The brief uses Background, Goals, Execution Plan, Acceptance Criteria, and Validation Commands.
• Optional Background subsections are used only when they improve clarity.
• Goals describe outcomes, not internal implementation steps.
• Acceptance criteria describe observable or verifiable outcomes.
• Validation commands are relevant to the touched area.
• If saved, the file lives in the correct docs/tasks/ lifecycle folder.
• If behavior or technical contracts change, the brief calls out the expected specs map update.

Task Lifecycle

Use this skill whenever a task changes state:

• A task is picked up and work begins → backlog → doing
• A task is finished → doing → done
• A task is put on hold or deprioritized → doing → backlog
• A task is abandoned or superseded → any → trash

This skill manages documentation flow only. It does not manage git branches, PRs, or worktrees.

Folder Meanings

Transition Playbooks

backlog → doing

When the user selects a task to start:

1. Identify the plan file in docs/tasks/backlog/.
2. Move it to docs/tasks/doing/.
3. Confirm the move to the user.

doing → done

When the user says a task is complete:

1. Identify the plan file in docs/tasks/doing/.
2. Move it to docs/tasks/done/.
3. Invoke the code-map-maintainer skill to check whether docs/code_maps/feature_map.yaml or docs/code_maps/logic_map.yaml need updating based on what the task changed.
4. Remind the user: if a .worktree/ directory exists for this task, it can be manually removed.

doing → backlog

When the user puts a task on hold:

1. Identify the plan file in docs/tasks/doing/.
2. Move it to docs/tasks/backlog/.
3. Confirm the move to the user.

any → trash

When the user abandons or supersedes a task:

1. Identify the plan file in its current folder.
2. Move it to docs/tasks/trash/.
3. Confirm the move to the user.

Identifying the Right File

When the user refers to a task by name (not exact filename):

1. List files in the relevant folder(s).
2. Match by keywords in the filename.
3. If ambiguous, show the user the candidates and ask them to confirm before moving.

What This Skill Does NOT Do

• Does not merge, close, or create PRs or branches.
• Does not delete worktrees — only reminds the user to clean up manually.
• Does not check whether code is actually implemented or merged before moving a file.
• Does not manage tasks outside docs/tasks/.

Tmux Agent Master

Use this skill when a project coordinates tmux-backed worker agents.

This skill answers:

• Which worker agents exist?
• How should a new worker be created?
• What is each worker good for?
• Which worker should receive a given task?
• What must be verified before trusting that a worker is ready?

Pair it with tmux-worker-steward whenever the master assigns concrete work. This skill manages the worker pool and routing. tmux-worker-steward manages delegation, supervision, output review, and correction.

Worker Registry

Each project should maintain a short worker registry before using tmux workers. The registry may live in this skill, a project AGENTS.md, or another repo-local instruction file.

Record each worker with:

### <worker-name>

- Session: `<tmux-session-or-window>`
- Working directory: `<absolute-or-repo-relative-path>`
- Role: <primary role>
- Strengths: <what this worker is good at>
- Best use: <task shapes to send here>
- Cost profile: <cheap, moderate, expensive, scarce, etc.>
- Boundaries: <what this worker should not decide or do>
- Submission method: <Enter, Ctrl+Enter, headless command, or other verified path>

Keep worker identity separate from worker role. A model, CLI, or session can be replaced while the role remains useful.

Creation Protocol

Before creating a worker:

1. Define the worker role and why an existing worker is not enough.
2. Choose a stable session name that includes the project and role.
3. Choose the working directory.
4. Decide allowed actions: read-only, command execution, network/search, editing, or explicitly no destructive actions.
5. Decide how the worker will receive prompts and how readiness will be checked.

After creating a worker:

1. Verify the session exists.
2. Verify the process is running in the intended working directory.
3. Send a small visible probe or use the worker's non-interactive command mode.
4. Confirm the prompt was submitted, not merely typed into an input box.
5. Add or update the worker registry entry.

Useful inspection commands:

tmux list-sessions
tmux list-windows -a
tmux list-panes -a -F '#{session_name}:#{window_index}.#{pane_index} window=#{window_name} cmd=#{pane_current_command} cwd=#{pane_current_path} title=#{pane_title}'
tmux capture-pane -p -t <session-or-pane>

Routing Rules

Match workers to task properties:

• Final judgment, code changes, or high-risk decisions: keep with the master.
• Second opinion, risk review, or competing design: use a strong reasoning worker.
• Broad repo search, document survey, or evidence gathering: use a scout worker.
• Cheap bounded summarization, counting, formatting, or checklist work: use a low-cost worker.

Do not delegate final authority. Worker output is advisory until reviewed by the master or steward.

Authority Boundaries

The master owns:

• task decomposition
• worker selection
• permission boundaries
• final synthesis
• deciding what evidence is trustworthy
• deciding whether code should change

Workers may:

• inspect files, logs, docs, artifacts, and process state within their scope
• produce summaries, candidate explanations, options, and recommendations
• run allowed commands when the project and user allow it

Workers must not:

• perform destructive actions without explicit approval
• make final release, merge, deletion, or irreversible infrastructure decisions
• treat their own output as accepted without master/steward review

Readiness And Submission Checks

Never assume a tmux worker received a task just because text appears in the pane. Verify one of:

• the worker is thinking
• the worker is running tools or commands
• the worker has started responding
• the non-interactive command returned an output artifact

If submission is uncertain, correct the interaction before waiting for results.

Handoff To Steward

When assigning concrete work, hand off to tmux-worker-steward with:

• selected worker
• objective
• scope
• allowed actions
• forbidden actions
• expected output
• evidence requirements

The steward should supervise the worker and review the answer before it reaches the user or drives implementation.

Tmux Worker Steward

Use this skill when the master assigns work to tmux-backed worker agents.

This skill answers:

• How should the worker assignment be written?
• How should worker progress be supervised?
• How should worker answers be reviewed?
• When should a weak answer be corrected instead of passed through?

This skill pairs with tmux-agent-master:

• tmux-agent-master creates, registers, inspects, and selects workers.
• tmux-worker-steward delegates, supervises, reviews, and corrects worker output.

Steward Responsibilities

1. Translate the user's intent.

   • Preserve the real objective, not just the literal wording.
   • Make implicit constraints explicit.
   • Remove ambiguity before handing work to a worker.

2. Write precise assignments.

   • State objective, context, scope, allowed actions, forbidden actions, and expected output.
   • Ask for evidence, not impressions.
   • Tell the worker what not to conclude without proof.

3. Supervise execution.

   • Verify the prompt was actually submitted.
   • If the worker reports a blocker, decide whether it needs clearer scope, smaller work, permission, or a different worker.
   • Answer worker questions from existing context when safe.
   • Bring true user decisions back to the user.

4. Review output.

   • Separate useful evidence from unsupported interpretation.
   • Check whether the answer addresses the assignment.
   • Identify missing evidence, timeline gaps, overconfident claims, and invented precision.
   • Do not pass through weak answers as final.

5. Correct weak reasoning.

   • Name the reasoning failure, not just the wrong conclusion.
   • Explain why it matters.
   • Send a revised task with concrete evidence requirements.

Assignment Template

Use this shape when sending work to a worker:

Objective:
<What we need to learn or produce.>

Context:
<Only the relevant background. Distinguish facts from assumptions.>

Scope:
<Files, commands, logs, sessions, hosts, branches, time range, or artifacts to inspect.>

Allowed actions:
- <Read-only inspection, commands, search, edits, etc.>

Forbidden actions:
- Do not modify files unless explicitly allowed.
- Do not use destructive commands.
- Do not infer root cause without direct evidence.
- Do not make final decisions for the master.

Output:
- Confirmed facts with evidence.
- Candidate explanations, if relevant.
- What is not yet proven.
- Recommended next step.

Submission Verification

After sending a task to a tmux worker, verify that the prompt was submitted and the worker left the input state.

Do not assume tmux send-keys ... C-m worked until the pane shows one of:

• the worker is thinking
• the worker is running tools or commands
• the worker has started responding

If the prompt remains in the input box, submit it correctly before waiting.

Reviewing Worker Answers

Before trusting a worker answer, check:

• Did it answer the actual question?
• Did it use the requested scope?
• Did it distinguish facts, hypotheses, and unknowns?
• Did it cite concrete evidence such as file paths, commands, logs, timestamps, artifacts, or code paths?
• Did it overclaim with words like "certainly", "only", "must", "proved", or "root cause"?
• Did it confuse symptoms with causes?
• Did it ignore a simpler explanation?
• Did it propose a verification step for unresolved uncertainty?

Correction Template

Use this when a worker answer is not ready to trust:

Your answer is not ready to trust yet.

Problem:
<Name the reasoning failure, not just the wrong conclusion.>

Why it matters:
<Explain the insight or evidence standard that was missed.>

Revise by:
- <Concrete correction 1>
- <Concrete correction 2>
- <Evidence or verification required>

Return only:
<Exact output format requested.>

Common Reasoning Failures

• Narrative overfit: building a coherent story before evidence supports it.
• Event mixing: combining facts from different runs, hosts, branches, commands, or time windows.
• Symptom-as-cause: treating a warning, missing file, missing log, or vanished process as the root cause.
• Unsupported uniqueness: saying "the only cause" without ruling out alternatives.
• Invented precision: naming exact lines, exceptions, exit codes, or behavior without direct evidence.
• Tool-output laundering: repeating partial command output as if it proved more than it does.
• Premature implementation: proposing a fix before the failure mode is understood.

When To Keep Work With The Master

Do not delegate when the task is:

• final synthesis after multiple workers report back
• irreversible or destructive
• a decision that changes project direction
• sensitive to user preference or product judgment
• too ambiguous to scope safely

In those cases, the steward may gather narrow evidence from workers, but the master keeps the decision.