chalk

name	chalk
description	Track session intent and progress against GitHub Issues, and write every GitHub-bound prose body (issue, comment, description, progress update) in the chalk voice. Use when the user says "chalk
version	0.3.0
user-invocable	true
disable-model-invocation	false

Chalk — GitHub Issue Tracking

Interpret MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, etc. per RFC 2119.

Before you draft anything GitHub-bound

Every issue body, issue description, chalk comment, progress section, and PR description you touch in this session MUST be drafted against the guidance in this skill and in VOICE.md at the plugin root. Do not rely on your own default prose habits — they will not match the chalk voice, and the artefact will read wrong.

Before writing any such prose:

1. If you haven't already, Read VOICE.md at the plugin root — it holds the quadrant framing (explanation vs reference vs how-to vs tutorial) and the concrete/abstract examples. Issues, comments, and PRs are all explanation artefacts.
2. Skim the "Writing issue and PR descriptions" section below for the section palette (Context, Symptoms, Root cause, Evidence, Motivation, Invariants, Proposed approach, Reasons for/against, Usage, Changes, Implementation notes, Dead ends, Scope, Test plan).
3. Only then draft.

This is not optional for body composition. If you find yourself typing a GitHub-bound body without having consulted the voice guidance, stop and reload it.

What chalk does

Track work against a GitHub Issue. The issue description is the source of truth — a developer should be able to understand the current state of the issue by reading the description alone, without trawling through comments. Keep the description accurate as facts change (new failure modes, updated analysis, revised scope). Comments are the append-only session log — what was tried, decided, and learned.

Understanding Why

Chalk's job is to capture the why, not just the what — and the diff won't carry that reasoning on its own. Before starting anything beyond a trivial change, make sure you understand two things:

• Why this change — what problem it solves, what it unblocks, what constraint drove it.
• Why now — what prompted it today. A deadline, a dependent piece of work, a recent incident, someone else blocked on it?

If either isn't obvious from the issue, the conversation, or the code you've read, ask the user before starting. A one-sentence answer now is cheaper than reconstructing the reasoning later from the diff.

Trivial changes (typo fixes, mechanical bumps, one-line config tweaks) don't need this step — the motivation is self-evident. Non-trivial changes (refactors, new features, non-obvious fixes, scope decisions) do: the issue description, the chalk comment, and the commit message all depend on you having it.

Issue Relationships

Use parent/child and blocked-by liberally — they carry structure the description can't, and they answer two questions cheaply that prose would answer expensively.

• Parent / sub-issues: when work naturally nests, link them. A sub-issue inherits the parent's motivation, so its own description can stay focused on the specific slice. Good fit for epic → sub-tasks, or a broad refactor split into reviewable pieces.
• Blocked-by: for order-dependent work. This is the one that pays back most — a filter for "open, un-blocked" becomes the queue of workable cards, and nobody has to triage to find out what they can pick up today.

Wire relationships in the same session they emerge. When creating a new issue that depends on or belongs under existing work, link it immediately — deferring it usually means the link never gets made. When starting on an issue, scan its neighbours for why-now context: a parent epic or a recently-unblocked predecessor often explains why this is the card to pick up today.

The github agent has GraphQL recipes for reading and mutating these relationships (addSubIssue, addBlockedBy, and the neighbourhood query).

Writing issue and PR descriptions

Issue and PR descriptions are explanation artefacts (see VOICE.md at the plugin root). The reader needs to understand why this matters and why the approach is shaped this way.

Common sections — all explanation, with reference-shaped evidence embedded where useful:

• Summary — one or two sentences on what's happening.
• Context / Motivation — how was this observed, or why does this matter? Environment, deployment, test configuration, links to CI runs, logs, dashboards, prior PRs, the broader initiative. Often the most valuable section — without it, a reader can't assess whether the issue applies to them or where a PR fits.
• Symptoms (bugs / incidents) — observable behaviour, error messages, affected conditions (e.g. "multi-writer only", "under chaos monkey testing"). Evidence-shaped.
• Root cause / Analysis (bugs / incidents) — why it's happening, grounded in evidence (log excerpts, stack traces, block file analysis, annotated offset tables).
• Evidence (bugs / incidents) — concrete artefacts: replica log dumps, application log excerpts with timestamps, block file contents, message type distributions. Annotate them — raw dumps without explanation are noise.
• Current state (refactors / features) — a concrete sketch of what exists today, in enough detail that the gap to the future state is visible. Reference-shaped: name the specific types, functions, flags, or files that the change touches.
• Future state (refactors / features) — the target end state. What the new world looks like once the change is shipped. Concrete and structural — the reader should be able to picture the resulting code or system shape from this section alone.
• Invariants / Constraints — non-obvious things the solution must preserve.
• Out of scope — what's explicitly not in this change, with reasons. Reference related issues/PRs that pick those pieces up.
• Alternatives considered — other designs or approaches at the same level of abstraction as the chosen one, with a sketch of each and the trade-offs that ruled it in or out. Dated rejections ("Rejected on 2026-05-23 because …") help the next reader who's tempted to reopen the question. Implementation-strategy choices (refactor-in-place vs. parallel impl, big-bang vs. incremental) aren't alternatives at this level — they belong in Implementation.
• Decision rationale — compare the chosen approach against each alternative on the points that differentiate them. Reads as a side-by-side, not a re-summary of the chosen approach.
• Implementation — direction and high-level plan for an issue; what landed for a PR. Step-by-step granular execution (which sub-task next, what files to touch) belongs in the chalk comment, not here.

PRs additionally draw from:

• Usage (user-visible features) — concrete examples (SQL queries with realistic output, CLI invocations, config snippets). Show what the feature looks like.
• Changes (multi-commit) — a numbered list of commits with a sentence each, so the reviewer knows the intended reading order.
• Implementation notes — grouped by sub-concern, not a flat list. Non-obvious design choices, key invariants, counter-intuitive bits.
• Dead ends — "tried X, didn't work because Y" prevents the reviewer from suggesting X.
• Test plan — what was tested and how.

Not every description needs all of these. A flaky test issue might just need the failure mode, stack trace, and conditions. A small bugfix PR might just need summary and test plan. A large feature PR might need context, usage examples, implementation notes, and scope. A refactor PR should call out that behaviour is intentionally preserved. Use judgement.

Ordering

Sections roughly flow: setup → state → decision → plan.

• Setup: Summary, Context / Motivation. The why-we're-here.
• State: Current state and Future state (refactors / features); Symptoms, Root cause, Evidence (bugs / incidents). The what-it-looks-like, today and at completion.
• Decision: Out of scope, Alternatives considered, Decision rationale, Invariants / Constraints. The why-this-path-and-not-others.
• Plan: Implementation, and (for PRs) Test plan. At the end.

The explanation-quadrant material (why this, why this way) sits above the reference-shaped step list. A reader who only scans the top of the issue should still understand the what and why; the how lives at the bottom.

Injecting Chalk Into Plans

When chalk is active, every implementation plan MUST include chalk steps as concrete plan steps. This is how chalk stays in sync — it rides the plan, not the session. Always include the issue number in each chalk step so it survives context compaction.

Inject these steps into the plan document:

1. Draft and create chalk comment on #N — compose the comment body in the main context, then hand it to the chalk agent to post — if one doesn't already exist for this session. Unless the user has specified otherwise, the same agent call MUST ensure the current user is an assignee on the issue (add @me if not already present — do not displace existing assignees).
2. (... implementation steps ...)
3. Draft and update chalk comment on #N — compose the updated body in the main context (outcomes, decisions, dead ends, and anything surprising), then hand it to the chalk agent.
4. Draft and update progress on #N — compose the new Progress section in the main context, then hand it to the chalk agent to write it back.

All GitHub interaction goes through the chalk agent (Task(subagent_type="chalk:github")). Run chalk agent write calls (create comment, update comment, update progress) in the background. Activation reads must be awaited — the result is needed before proceeding.

Plan Mode Integration

When chalk is active and you write a plan, the plan document MUST include:

1. First step: create or update the session comment with the plan's work items before any implementation begins.
2. Final step (after commit): update the session comment with outcomes, decisions, and anything surprising.

These are plan steps like any other — they appear in the plan file the user reviews.

Auto-Activation

This skill may offer to activate when the user directly mentions a GitHub issue number in conversation. Only offer when the issue number appears in the user's own message — not in code, file contents, build output, or other non-conversational context.

When offering, keep it brief: "Want to track this session against #123? (type chalk #123 to activate)"

Do NOT automatically read the issue. Issue content is only fetched after the user explicitly invokes chalk #N. If the user does not explicitly invoke chalk, do not read or fetch any issue content.

Commands

• chalk #N — track this session against issue N
• chalk new — create a new issue and track against it
• chalk status — show what you're tracking (report the issue number and current Progress summary)
• chalk off — finalize the current comment (if one is in progress) via the chalk agent, then stop tracking

Activation: chalk #N

1. Use the chalk agent to read the issue, its recent comments, and its one-hop neighbourhood (parent, sub-issues, blocked-by, blocking).
2. Internalize the issue context without repeating the entire issue to the user.
3. If no ## Progress section exists in the issue description, ask the chalk agent to add one.
4. If the change is non-trivial and the why or why now isn't obvious from the issue or its neighbours (see "Understanding Why"), ask the user before starting.
5. Tell the user you're tracking against #N.

Activation: chalk new

1. Ask the user for a title and brief context — including why now, if it's not already clear. See "Understanding Why".
2. Draft the issue body yourself in the main context, following "Writing issue and PR descriptions" above and the voice in VOICE.md. Include a ## Progress section at the end. Do not delegate this drafting to the agent — it won't have the conversation context and will produce a thinner description than you can.
3. Pass the title and the fully-drafted body to the chalk agent to create the issue.
4. Note the issue number from the agent's response.
5. Tell the user you're tracking against the new issue.

Two Layers of State

Issue Description — The Progress Checklist

Chalk owns a ## Progress section within the issue description. Leave everything else untouched.

The ## Progress section contains:

• A checklist of all known work items (checked/unchecked).
• A Status line (in-progress, completed, blocked).
• An Open Questions checklist if there are unresolved items.

## Progress

**Status**: in-progress

- [x] Investigate flaky test in expression_test
- [x] Fix root cause: race condition in temporal bounds
- [ ] Add regression test for concurrent temporal queries

### Open Questions

- [ ] Should we also make TemporalBounds immutable? (see comment)

Update the progress section (via the chalk agent) whenever the checklist changes — items added, completed, or deferred.

Updating the issue description (beyond the Progress section): update factual content when the current state has changed (new failure mode, updated context, revised scope). Preserve the user's framing and intent — don't rewrite the narrative, just keep the facts current.

Comments — One Per Session

Each session gets one comment. The comment is created when work begins and updated as the session progresses.

Across sessions, this gives you an append-only log: scroll down = chronological history of implementation.

Delegating to the Chalk Agent

All GitHub interaction goes through the chalk agent. The main conversation MUST NOT call gh issue or gh api directly for chalk updates. This keeps the main context clean and avoids filling it with API output.

You compose; the agent executes. The agent is a small-model mechanics layer — it runs gh and reports results. It does not have your conversation history, the chalk comments you've read, the diff, or the voice guidance in full. Draft issue bodies, comment bodies, Progress sections and PR descriptions in the main context before calling the agent, following "Writing issue and PR descriptions" above and the voice in VOICE.md. The agent's prompt MUST include the full content ready to post verbatim. Passing "here are some bullet points, write this up" is not acceptable — that pushes an explanation-quadrant job onto a model that can't do it well and loses the reasoning the reader actually needs.

To create or update a chalk comment, launch the chalk agent via the Task tool:

Task(subagent_type="chalk:github", prompt="...")

The prompt MUST contain:

• The issue number
• What action to take (create comment, update comment, update progress, create issue, create PR)
• The fully-drafted content to write, ready to paste verbatim into GitHub
• Any project-specific GitHub conventions that apply to this operation (see below)

Run chalk agent write calls in the background. Await read calls (activation) — the result is needed to proceed.

Passing project-specific conventions

The chalk agent is deliberately generic — it doesn't know which project board new issues should land on, what the default labels are, or who reviews PRs. Those conventions live in the calling project (typically the project's CLAUDE.md, or explicit user instructions during the session).

Before calling the agent, scan your current context for project-specific GitHub conventions relevant to the operation — project boards, default labels, milestones, assignees, reviewers, base branches — and include them verbatim in the agent's prompt. Do not try to paraphrase or pre-interpret them; pass them through and let the agent apply them alongside its defaults.

If a convention is session-specific or has been overridden by the user for this operation (e.g. "don't add this one to the board"), reflect that in the prompt rather than the project default.

Comment Format

### Chalk — Short description of this task

- [ ] First work item
- [ ] Second work item

<details><summary>First work item</summary>

Details of what was explored, decided, implemented...

</details>

<details><summary>Second work item</summary>

Details...

</details>

No date in the header — GitHub timestamps the comment itself.

Rules:

• The checklist is the scannable overview. Each item mirrors a <details> block below.
• Check items off as you complete them.
• Add new items as work emerges.
• Keep details blocks focused — one per theme or work item.

Writing style: each <details> block is an explanation chunk — what was explored, decided, tried. The checklist above is navigation, not a separate quadrant. Follow the explanation-quadrant voice in VOICE.md. Details blocks should read like knowledge-sharing, not a changelog.

Lifecycle of a Comment

Create when starting work — when you have a plan and are about to implement. If there's no formal plan (e.g. a quick bugfix), still create a comment before starting work. Creating the chalk comment is the signal that you're picking the issue up: unless the user has specified otherwise, the same agent call ensures the current user is an assignee (adding @me if not already present — chalk only adds, never displaces).

Update as the session progresses — frequently, and without asking. Chalk updates are part of the work, not a separate task that needs the user's permission each time. Treat them like staging a file before committing: just do it, then move on.

• Check off completed items as they land.
• Fill in details blocks with decisions, findings, dead ends.
• Add any items that emerged during implementation.

The user MUST NOT have to prompt each update. If there's something new to record (a decision, a dead end, a completed item, a surprising finding), update the comment — don't ask "should I update chalk?" first.

Before stopping or ending the session: finalize the comment via the chalk agent. Update the Progress section if the overall picture changed.

Before context compaction: ensure the comment captures all progress so far. Include the issue number in your compaction summary so you can resume tracking afterward.

After context compaction (resuming): if your compaction summary mentions a chalk issue number, re-activate by reading the issue and the session comment. Continue updating the existing comment — do not create a new one.

Example Comment

See examples/implementation-comment.md for a realistic filled-in example.

Constraints

• There MUST be one comment per session.
• Chalk MUST NOT edit a chalk comment authored by a different user without the user's express permission for that specific update. If another developer's chalk comment is the most recent, create a new comment instead of editing theirs.
• The ## Progress section MUST be the canonical state of the issue checklist.
• All GitHub interaction MUST go through the chalk agent. The main context MUST NOT call gh directly for chalk updates.
• The issue description MUST be kept accurate — update facts when they change, but preserve the user's framing and intent.
• <details> blocks MUST contain enough context that a future session can pick up where you left off.
• All writing MUST follow the voice in VOICE.md at the plugin root — issues, PRs, and chalk comments are explanation artefacts.