tickets-and-logbook

name	tickets-and-logbook
description	Use when doing sustained or multi-step work in any project — feature work, refactors, investigations, or anything touching multiple files or sessions. Defines the ticket body format, status lifecycle, and LOGBOOK.md conventions used across all projects.

Tickets and Logbook

This skill enforces work tracking discipline via the project's ticket source and a development logbook.

It is authoritative and applies across all sustained or multi-step work.

---

Detecting the project's ticket source

Before applying this skill, detect where tickets live for this project. Probe in priority order; stop at the first hit:

1. Airtable — AGENTS.md / CLAUDE.md / README.md references an Airtable base ID (app[A-Za-z0-9]{14,}) and table ID (tbl[A-Za-z0-9]{14,}), and mcp__Airtable_MCP_Server__* tools are available.
2. Linear — Linear MCP tools are available AND AGENTS.md / CLAUDE.md mentions a Linear team or project.
3. GitHub Issues — gh repo view --json nameWithOwner succeeds AND gh issue list --state open --limit 1 returns ≥1 issue.
4. Markdown — docs/TICKETS.md, TICKETS.md, or similar exists with parseable entries.

If none are found, halt and ask the user where tickets live before doing any tracked work.

The rest of this skill describes the discipline in source-agnostic terms; map each operation to the detected source's tooling (Airtable MCP, Linear MCP, gh, or markdown edits).

---

Scope

This skill applies whenever an agent:

• Makes non-trivial changes
• Touches multiple files
• Discovers deferred or follow-up work
• Performs investigation, refactor, or feature work
• Produces artifacts meant to guide future work

---

Core Rules

1. No Drive-By Changes

Agents MUST NOT make untracked changes.

Every meaningful change MUST be associated with either:

• An existing open ticket
• Or a newly created ticket

---

2. Ticket Format

Every ticket MUST carry these fields (translate to whichever schema the source uses):

## Problem
Clear description of what is broken, missing, or needed.

## Approach
- Step 1
- Step 2

## Dependencies
Depends on: T-N — reason   (or "—")

## Acceptance Criteria
- [ ] Testable criterion 1
- [ ] Testable criterion 2

## Testing
- How to verify criterion 1
- How to verify criterion 2

## Logbook
— (updated with YYYY-MM-DD entry links when work is logged)

Title format: Short imperative title. The ticket source assigns its own identifier (Airtable record ID, Linear ID, GitHub issue number); don't prefix the title with it.

References: T-N throughout this skill is a placeholder for the source's native reference — #N for GitHub Issues, the issue key for Linear, the record's primary field for Airtable. Use the native form in Dependencies, logbook entries, and commit messages.

Categorisation: Every ticket MUST carry exactly one thematic tag and one status tag — implemented as Airtable single-selects, Linear labels, GitHub labels, or markdown front-matter depending on the source.

Notes: When a significant decision or finding changes a ticket mid-flight, add a comment / activity entry rather than editing the body. The body is the original spec; comments are the decision log.

---

3. Status Lifecycle

Valid statuses (universal across sources). Normal flow is proposed → ready → in-progress → closed, with blocked reachable from any active state:

Status	Meaning
proposed	Idea or finding — not yet scoped or ready to build
ready	Fully scoped, no blocking dependencies, can be picked up
in-progress	Actively being worked
blocked	Cannot proceed — dependency or external blocker noted in a comment
closed	All acceptance criteria met, logbook entry written, code committed

Agents MUST update the status whenever a ticket changes state.

Map status to the source's mechanism:

• Airtable — set the Status single-select field via mcp__Airtable_MCP_Server__update_records
• Linear — call the workflow-state mutation via Linear MCP
• GitHub — gh issue edit <N> --add-label "in-progress" --remove-label "proposed"
• Markdown — edit the status column or front-matter

A ticket is not done until:

1. All acceptance criteria are met
2. A logbook entry exists in LOGBOOK.md
3. Code is committed (and pushed, if the project's workflow requires it)

---

4. Common Operations

The four operations every workflow needs — perform each via the source's native tooling:

Create a new ticket — populate every field in §2 (Problem, Approach, Dependencies, Acceptance Criteria, Testing, Logbook). Set status to proposed or ready depending on whether scoping is finished. Set the thematic tag.

View a ticket — read the body before starting work. Re-read mid-task if requirements feel ambiguous.

List active work — filter by status (in-progress, proposed, blocked) using the source's query mechanism. Use this when picking what to work on next or when surfacing the open work surface to the user.

Update status — flip the status whenever state changes (pickup, block, unblock). Don't batch.

Close a ticket — set status to closed with a one-line note pointing at the logbook entry date and the commit SHA.

Cascade unblock — when a ticket closes, walk its downstream dependents (tickets that listed it in their Dependencies / Blocked By) and either remove the dependency or flip them to ready if newly unblocked. This is easy to forget; bake it into the closure step.

---

5. Logbook Requirements

A LOGBOOK.md file MUST exist in the project's docs/ directory (or root if no docs/ exists).

A logbook entry MUST be written:

• At the end of every meaningful work session
• When a ticket moves to in-progress or is closed
• When a significant architectural decision or trade-off is made

Entry format:

## YYYY-MM-DD — Session or decision title

**Tickets:** T-N, T-N

**What changed:**
- Bullet summary of changes made

**Why:**
- Reason for the approach chosen

**Decisions made:**
- Any architectural, scope, or approach decisions

**Risks / follow-ups:**
- Known risks or deferred work discovered during this session

After writing the entry, update the Logbook field on the ticket (or add a comment) referencing the entry date.

---

6. Roadmap Coupling (If Applicable)

If a roadmap exists:

• Roadmap edits MUST be reflected in tickets
• Ticket completion MUST map back to roadmap objectives

---

Completing a Ticket

To close a ticket as done:

1. Verify all acceptance criteria checkboxes are checked (or note any deferred)
2. Write a logbook entry in LOGBOOK.md
3. Update the ticket's Logbook field with the entry date (or add a comment)
4. Set status to closed with a note: "Done. Logbook: YYYY-MM-DD entry. Commit: <sha7>."
5. Walk downstream dependents and remove the dependency (and flip any newly-unblocked blocked tickets to ready / open in the same pass)
6. Commit all changes with a message referencing the ticket: fix(scope): T-N — resolve <issue>
7. Push to remote if the project's workflow requires it

---

Enforcement

• Work performed without a ticket is invalid.
• Closed tickets without logbook entries are incomplete.
• Tickets missing required body sections are malformed and must be fixed before the ticket can be acted on.
• This skill overrides workflows that attempt to bypass tracking discipline.

---

Intent

This skill exists to ensure:

• Traceability
• Accountability
• Durable decision memory
• Smooth handoffs between humans and agents