メニュー
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.
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
| 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. |
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.
Before applying this skill, detect where tickets live for this project. Probe in priority order; stop at the first hit:
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.AGENTS.md / CLAUDE.md mentions a Linear team or project.gh repo view --json nameWithOwner succeeds AND gh issue list --state open --limit 1 returns ≥1 issue.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).
This skill applies whenever an agent:
Agents MUST NOT make untracked changes.
Every meaningful change MUST be associated with either:
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.
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:
Status single-select field via mcp__Airtable_MCP_Server__update_recordsgh issue edit <N> --add-label "in-progress" --remove-label "proposed"A ticket is not done until:
LOGBOOK.mdThe 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.
A LOGBOOK.md file MUST exist in the project's docs/ directory (or root if no docs/ exists).
A logbook entry MUST be written:
in-progress or is closedEntry 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.
If a roadmap exists:
To close a ticket as done:
LOGBOOK.mdclosed with a note: "Done. Logbook: YYYY-MM-DD entry. Commit: <sha7>."blocked tickets to ready / open in the same pass)fix(scope): T-N — resolve <issue>This skill exists to ensure:
Process raw-extracted JSON files from PDF book extractions into clean, well-structured markdown. Use this skill whenever a user uploads a raw-extracted.json (or similar JSON with metadata and chunks arrays) from a PDF text extraction pipeline, or when they mention cleaning up, formatting, structuring, or organizing extracted book text. Also trigger when the user mentions OCR output, pypdf extraction, book chapters, or converting messy PDF extractions into readable markdown. This skill handles books with varying extraction quality — from clean text to garbled OCR — and adapts its approach accordingly.
This skill should be used when the user invokes /code-documentation, or asks to "write/generate/audit/update documentation", "write a README", "document this API or codebase", "write a tutorial / how-to / runbook", "write user help docs", "generate docstrings", "write an ADR or RFC", "create a changelog", "produce llms.txt or AGENTS.md", or "turn these docs into a doc site". Produces first-class documentation for any audience (end users, API consumers, contributors, operators, evaluators, AI agents) across all four Diátaxis modes, for the full lifecycle — authoring, generating from a codebase, auditing, and maintaining. Emits publish-ready Markdown or structured content for Docusaurus, MkDocs, Sphinx, Starlight, Mintlify, or Volume.
React composition patterns that scale. Use when refactoring components with boolean prop proliferation, building flexible component libraries, or designing reusable APIs. Triggers on tasks involving compound components, render props, context providers, or component architecture.
Use when the user wants to brainstorm blog topics, generate or score article ideas, review/approve content ideas, track article status, or manage editorial planning — including mentions of "content calendar", "editorial calendar", "blog ideas", "article pipeline", "content backlog", or "publishing schedule".
Checklist for auditing architecture contracts in a develop-by-contract environment. Covers the failure modes most commonly found during contract review: status drift, AI-invented decisions, cross-contract fact drift, stale feature references, missing state specs, and business policy gaps.
Use when analyzing, auditing, reviewing, or explaining a codebase, system, or project state — whenever written claims could mix observed fact with interpretation.