shiplog

name shiplog description Git-as-knowledge-graph workflow for traceability. Use when planning work, brainstorming designs, creating/managing issues and PRs, tracking architectural decisions, or resuming prior sessions. Slash command /shiplog. Shiplog The captain's log for your codebase. Every decision, discovery, and change logged as you ship code. Use GitHub as a complete knowledge graph where every brainstorm, commit, review, and decision is traceable. This skill orchestrates existing skills and references; it defines when and how to invoke them and what documentation protocol to follow. Core Principle Nothing gets lost. Every brainstorm becomes an issue. Every issue drives a branch. Every branch produces a PR. Every PR is a timeline of the entire journey. Git becomes the uber-memory. Golden-Path Walkthrough A complete issue-to-merge example using a concrete fake issue #999 . Follow this sequence and every artifact produced will pass the acceptance checklists in commands/shiplog/*.md . Step 1 — Plan Capture ( /shiplog plan ) A brainstorm produces: "Add rate-limit headers to the API so clients can back off intelligently." Load commands/shiplog/plan.md and create the issue: gh issue create \ --title "[shiplog/plan] Add rate-limit headers to API" \ --label "shiplog/plan" \ --body-file .tmp-plan.md Issue body (excerpt): <!-- shiplog: kind: state status: open phase: 1 readiness: ready task_count: 2 tasks_complete: 0 max_tier: tier-2 updated_at: 2026-04-18T10:00:00Z --> ## Tasks - [ ] **T1: Add X-RateLimit-* headers to response middleware** `[tier-2]` - **What:** Inject X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset on every API response. - **Verification:** curl the endpoint; confirm all three headers are present. - [ ] **T2: Document header semantics in API reference** `[tier-2]` - **What:** Add a "Rate Limiting" section to docs/api-reference.md. - **Verification:** Section exists and matches header values in integration test. Authored-by: claude/sonnet-4.6 (claude-code) Apply lifecycle label: gh issue edit 999 --add-label "shiplog/ready" Step 2 — Branch Setup ( /shiplog start ) Load commands/shiplog/start.md . Create the branch from the default branch tip (substitute your repo's default branch, e.g. main or master ): git fetch origin <default-branch> git checkout -b issue/999-rate-limit-headers origin/<default-branch> Swap label and update envelope: gh issue edit 999 --remove-label "shiplog/ready" --add-label "shiplog/in-progress" # Edit issue body: readiness: ready → readiness: in-progress Post session-start comment: [shiplog/session-start] #999: Starting work **Branch:** `issue/999-rate-limit-headers` **Starting tasks:** T1, T2 **Plan:** Add headers in middleware (T1) then document (T2). Authored-by: claude/sonnet-4.6 (claude-code) Step 3 — Commit Context ( /shiplog commit ) After implementing T1, load commands/shiplog/commit.md and commit: git add src/middleware/rate_limit.ts git commit -F .tmp-commit-msg.md # Commit message: feat(#999/T1): add X-RateLimit-* headers to response middleware # # Injects the three standard headers into every API response via middleware. # # Authored-by: claude/sonnet-4.6 (claude-code) Post commit-note on the issue: [shiplog/commit-note] #999: a1b2c3d feat(#999/T1): add X-RateLimit-* headers **What:** Middleware now injects X-RateLimit-Limit, -Remaining, and -Reset. **Why:** Clients need these to implement back-off without polling. **Verification:** curl localhost:3000/api/health — all three headers present. Authored-by: claude/sonnet-4.6 (claude-code) Repeat for T2 commit ( docs(#999/T2): document rate-limit headers in API reference ). Step 4 — PR Timeline ( /shiplog pr ) Load commands/shiplog/pr.md . Push and create the PR: git push -u origin issue/999-rate-limit-headers gh pr create \ --title "feat(#999): add rate-limit headers to API" \ --label "shiplog/history" \ --label "shiplog/issue-driven" \ --body-file .tmp-pr-body.md PR body includes: envelope ( kind: history ), summary, Closes #999 , Journey Timeline with both commits, Verification checklist, Reviews placeholder, and sig block: Authored-by: claude/sonnet-4.6 (claude-code) Last-code-by: claude/sonnet-4.6 (claude-code) *Captain's log — PR timeline by **shiplog*** Transition issue label: gh issue edit 999 --remove-label "shiplog/in-progress" --add-label "shiplog/needs-review" Step 5 — Cross-Model Review ( /shiplog review ) A different model (e.g., openai/gpt-5.4 (codex) ) loads commands/shiplog/review.md , reads the diff, and posts the signed review comment on the PR: [shiplog/review-handoff] #999: Review of PR #<PR> Middleware approach is correct. Headers match RFC 6585 semantics. Reviewed-by: openai/gpt-5.4 (codex, effort: high) Disposition: approve Scope: full diff Follow-ups: none The reviewer then updates the PR body review snapshot in place: Current state: approved Last reviewed by: openai/gpt-5.4 (codex, effort: high) Last reviewed at: 2026-04-18T15:00:00Z Reviewed commit: a1b2c3d Source artifact: <URL to review comment> Needs re-review since: — Step 6 — Merge Cross-model gate is satisfied ( Last-code-by: claude/sonnet-4.6 ≠ Reviewed-by: openai/gpt-5.4 ). Merge the PR. Remove all lifecycle labels from issue #999. GitHub closes #999 automatically via Closes #999 . When This Skill Activates User-invocable: /shiplog , /shiplog models , /shiplog <phase> /shiplog models : Re-runs the routing setup prompt. See references/model-routing.md . Auto-activate when ANY of these occur: User says "let's plan", "let's brainstorm", or "let's design" User explicitly requests traceability or knowledge-graph tracking Creating a new issue or PR with intent to document decisions Mid-work discovery requiring a new issue or stacked PR User asks "where did we decide X?" or "what's the status of Y?" Resuming work on an existing issue or PR Applying review feedback, fixing review findings, or addressing request-changes dispositions User references an issue or PR by number Issue or PR body footer contains Managed by **shiplog** (recognition trigger — do not add this footer proactively) Do NOT auto-activate for: Generic coding requests that do not need traceability Simple bug fixes or refactors that do not need durable workflow history Work where a more specific skill is the better fit Verb Grid Each /shiplog <phase> slash command maps to one sub-skill file. Load the file for that phase — it owns policy, templates, and acceptance checklist. Command What it does Sub-skill /shiplog plan Capture a brainstorm as a GitHub planning issue with envelope + task contracts commands/shiplog/plan.md /shiplog start Create a branch from an issue, swap lifecycle labels, post session-start comment commands/shiplog/start.md /shiplog hunt Triage open issues and PRs; rank by readiness; detect gate-satisfying reviews commands/shiplog/hunt.md /shiplog commit Stage and commit with ID-first format; post commit-note comment for significant commits commands/shiplog/commit.md /shiplog pr Push branch, create PR with journey timeline body, transition issue label commands/shiplog/pr.md /shiplog review Perform cross-model review; post signed comment; update PR body review snapshot commands/shiplog/review.md /shiplog lookup Search issues, PRs, and git log by #ID or keyword; return compact table first commands/shiplog/lookup.md /shiplog resume Re-orient to current branch; detect issue number; post session-resume comment commands/shiplog/resume.md /shiplog models : Re-runs the model-routing setup prompt. See references/model-routing.md . Canonical Kind → Tag → Label Map kind: in envelope YAML is the source of truth. Title tags ( [shiplog/<tag>] ) and GitHub labels ( shiplog/<label> ) are derived views on kind: . When a new artifact kind is defined, it is added here once and all three surfaces are updated together. kind: (envelope) Title tag [shiplog/<tag>] GitHub label shiplog/<label> Description state plan , session-start , session-resume , milestone , discovery , implementation-issue plan (planning issues) Current status snapshot of an issue or PR handoff session-start , review-handoff — Context transfer between tiers, tools, or sessions verification commit-note , review-handoff , verification verification Evidence of testing, review, or quality check commit-note commit-note — Reasoning behind a specific commit review-handoff review-handoff — Review request or review completion artifact amendment amendment — Correction or clarification for an existing signed artifact blocker blocker blocker Something preventing progress history history history Retrospective summary for knowledge retrieval Lifecycle labels ( shiplog/ready , shiplog/in-progress , shiplog/needs-review ) are not tied to an artifact kind: . They track issue/PR workflow state and are mutually exclusive. Apply them per the Triage Field Maintenance table below. Aspect labels ( shiplog/discovery , shiplog/stacked , shiplog/issue-driven ) classify the relationship between artifacts, not their content kind. They may coexist with lifecycle labels. For the full label set, color codes, and bootstrap CLI snippets, see references/labels.md (which cross-references this table as its canonical kind source). ID-First Naming Convention All artifacts use #ID as the primary key for fast, token-efficient retrieval. Semantic tag vocabulary for user-facing headings: plan , session-start , session-resume , commit-note , discovery , blocker , implementation-issue , handoff , review-handoff , history , amendment , milestone , and verification . Format: [shiplog/<tag>] <human title> . See the Canonical Kind → Tag → Label Map section for the authoritative mapping. Artifact Convention Example Branch issue/<id>-<slug> issue/42-auth-middleware Commit <type>(#<id>): <msg> feat(#42): add JWT validation Commit (task) <type>(#<id>/<Tn>): <msg> feat(#42/T2): add middleware chain PR title <type>(#<id>): <msg> feat(#42): add auth middleware PR body (closes) Closes #<id> Closes #42 PR body (partial) Addresses #<id> (completes ...) Addresses #42 (completes T1, T2) Task in issue - [ ] **T<n>: Title** [tier-N] - [ ] **T1: Add JWT** [tier-3] Timeline comment [shiplog/<kind>] #<id>: ... [shiplog/discovery] #42: race condition Stacked branch issue/<new-id>-<slug> issue/43-fix-race-condition Stacked PR title <type>(#<new-id>): ... [stack: #<parent>] fix(#43): race cond [stack: #42] Memory entry #<id>: <decision> #42: chose JWT over sessions Task IDs: Tasks carry local IDs ( T1 , T2 , ...) scoped to the issue. Commits use #<id>/<Tn> . Retrieval: gh issue list --search "#42" | git log --grep="#42" | git log --grep="#42/T1" | gh pr list --search "#42" Envelope Schema and Triage Fields