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.

Mode Selection

On first activation per project, ask the user which mode to use:

• Full Mode (default): Knowledge goes directly into issues and PRs. For personal projects, OSS, and teams that embrace documentation.
• Quiet Mode: Knowledge lives in a stacked knowledge branch (<branch>--log) with its own PR targeting the feature branch. For work environments where issues and PRs must stay clean.

Remember the choice via ork:remember or note it in project instructions.

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

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

Decision Tree

Match the user's intent and load the corresponding sub-skill:

User request arrives
  +--> [If .shiplog/routing.md missing: run setup from references/model-routing.md]
  +--> ["/shiplog models": re-run setup prompt, update config]
  |
  +-- "Let's brainstorm/plan/design X" -> shiplog:brainstorm
  +-- "Work on issue #N"               -> shiplog:branch
  +-- "I found a sub-problem"          -> shiplog:discovery
  +-- "Let's commit"                   -> shiplog:commit
  +-- "Ready for PR"                   -> shiplog:pr
  +-- "Where did we decide X?"         -> shiplog:lookup
  +-- Currently mid-work on a branch    -> shiplog:timeline

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, commit-note, discovery, blocker, implementation-issue, review-handoff, worklog, history, and amendment. Format: [shiplog/<kind>] <human title>.

Quiet Mode overrides:

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"

User-Facing Language

The phase numbers are internal workflow labels. Do not surface them to the user.

Preferred labels: Plan Capture, Branch Setup, Discovery Handling, Commit Context, PR Timeline, History Lookup, Timeline Updates.

Brand formatting: Always bold the word shiplog in user-facing text (messages, comments, PR bodies, issue bodies). Write it lowercase and bold: shiplog. This does not apply to code identifiers, branch names, CLI output, or other machine-readable contexts where markdown is not rendered.

Shell Portability

Keep the workflow cross-platform. See references/shell-portability.md for full guidance and Bash/PowerShell patterns.

Key rules:

• Prefer gh ... --body-file <temp-file> for multiline content.
• Break chained shell commands into separate steps when the shell operator differs.
• Keep Bash examples as the primary path; add PowerShell notes where syntax diverges.

GitHub Labels

shiplog manages a compact repo-level label vocabulary so issues and PRs stay filterable even when a reader never opens the body. See references/labels.md for the canonical label set, descriptions, and CLI snippets.

Label rules:

• On the first write operation in a repo, bootstrap or refresh labels with gh label create --force ....
• Apply labels at creation time with gh issue create --label or gh pr create --label.
• shiplog/blocker is stateful. Add it when work becomes blocked and remove it when the blocker is cleared.
• shiplog/ready, shiplog/in-progress, and shiplog/needs-review are mutually exclusive lifecycle labels.

Triage Field Maintenance

Issue envelope triage fields (readiness, task_count, tasks_complete, max_tier) and lifecycle labels must be kept current so triage scans produce accurate results.

Edit the issue body in place when these fields change. Triage metadata is derived state, so refreshing it does not require Updated-by: provenance.

Mandatory Issue Capture

Implementation trouble that materially affects the work must be durably recorded before the agent proceeds to the next material step or ends the turn.

What counts as a relevant implementation issue

• Failed attempts
• Hidden dependencies
• Risky workarounds
• Scope surprises
• Verification gaps
• Environment or tooling friction

What does not require capture

• Normal iteration where the final approach is obvious from the diff
• Minor typos or lint fixes resolved in the same commit
• Expected complexity that matches the task description

Capture rule

The timeline comment is the minimum: one paragraph explaining what happened, why it matters, and how it was resolved or deferred.

Agent Identity Signing

Every shiplog artifact must carry a provenance signature: <role>: <family>/<version> (<tool>[, <qualifier>])

Roles: Authored-by, Updated-by, Reviewed-by. See references/signing.md for full rules, edit provenance, and model detection.

Integration Map

This skill orchestrates. For activities that directly produce shiplog artifacts, convention-enforced workflows are internalized in references/.

Internalized workflows: Commit and PR workflows are internalized in references/ so shiplog conventions win over third-party defaults.

Graceful degradation: Internalized workflow -> external skill -> direct gh/git commands.

Edge Cases

• No issue exists: Let the user work. At first commit or PR, offer to create a tracking issue.
• Mid-work activation: Check branch name for issue/N-*. If found, add catch-up timeline comment via shiplog:timeline. If not, offer retroactive issue creation.
• Small tasks (< 30 min): Lightweight protocol - issue optional, branch still created, PR sections can be brief.
• Hotfix / emergency: Fix first. Create issue and PR after, backfilling the timeline.
• Quiet mode — feature PR merges: Close the --log PR. Knowledge is preserved in closed PR history.
• Quiet mode — feature branch rebased: Rebase --log branch onto updated feature branch. Use --force-with-lease.

Requirements

All recommended skills are optional. Internalized workflows live in references/; external skills remain optional enhancements.