[shiplog/plan] Quiet mode audit: slash commands and features are mode-unaware

## Context

Quiet mode was designed early in **shiplog**'s life as an alternative workflow where team-facing PRs stay clean and full knowledge trails live in a stacked `--log` branch/PR. Since then, many features have been added — slash commands (#108), verification profiles (#97), partial delivery (#79), discovery protocol refinements, closure verification (#17), edit provenance (#49) — without systematically verifying quiet mode coverage.

A thorough line-by-line audit of SKILL.md, README.md, all slash commands, and all reference files reveals **two layers of breakage:**

1. **Surface layer:** Every slash command and several SKILL.md phases are completely unaware of quiet mode — they post knowledge to the wrong place.
2. **Fundamental layer:** Quiet mode promises "clean GitHub for the team," but **shiplog freely creates issues** (`[shiplog/plan]`, `[shiplog/discovery]`, `[shiplog/stacked]`) which are just as visible and noisy as timeline content in PRs. Many teams using quiet mode use JIRA, Linear, or other external trackers for issues and only use GitHub for PRs — shiplog has no path for this.

## Design Summary

### The surface problem: slash commands bypass SKILL.md

The slash commands (`commands/shiplog/*.md`) were built as independent scripts that skip loading the 28KB SKILL.md. Quiet mode logic lives only in SKILL.md prose. Result: all 7 non-`models` commands do the wrong thing in quiet mode.

### The fundamental problem: issues are noise too

The entire **shiplog** architecture assumes issues exist: ID-first convention, commit format `(#<id>)`, branch naming `issue/<id>-<slug>`, task lists, evidence-linked closure. But in quiet mode, creating `[shiplog/plan]` and `[shiplog/discovery]` issues defeats the "clean" promise. A team that doesn't want timeline content in their PRs also doesn't want their issue tracker filled with AI-generated planning artifacts.

Many teams also use external trackers (JIRA, Linear, Shortcut, etc.) for issue management and only use GitHub for code and PRs. Quiet mode must support this workflow: the issue already exists elsewhere, GitHub gets only PRs and the `--log` knowledge branch.

### README and SKILL.md claim mismatches

Multiple marketing claims and core principle statements are **false in quiet mode**:

| Location | Claim | Reality in Quiet Mode |
|----------|-------|-----------------------|
| SKILL.md line 14 | "Every brainstorm becomes an issue" | Issues are noise; brainstorm goes in `--log` PR |
| SKILL.md line 14 | "Every PR is a timeline of the entire journey" | Feature PR is clean; timeline is in `--log` PR |
| README line 30 | "Every brainstorm becomes a GitHub Issue" | False |
| README line 35 | "Every PR tells the full story" | False — only `--log` PR does |
| README line 37 | "spin off a new issue" | Issues are noise |
| README line 45 | "captures the result as a GitHub issue" | False |
| README line 51 | "Design discussion becomes a GitHub Issue with tasks" | False |
| README line 55 | "PR with full journey timeline" | False — feature PR is clean |
| README line 267 | `/shiplog plan`: "capture it as a GitHub Issue" | False |
| README line 269 | `/shiplog pr`: "Create a PR with a journey timeline body" | False — clean PR |

## Approach

### Quiet mode issue policy: "Attach, don't create"

In quiet mode, **shiplog** should follow this decision tree for issues:

```
Need to reference an issue?
  |
  +-- Does a GitHub issue already exist (user-created, from external tracker sync)?
  |     +-- YES: Attach to it. Use its #ID. Do NOT add timeline comments on it (use --log PR).
  |     +-- NO:
  |           +-- Ask user: "Create a tracking issue, or work PR-only?"
  |                 +-- "Create issue": Create minimal issue (title + task list only, no brainstorm prose, no shiplog labels)
  |                 +-- "PR-only": Use --log PR as the sole knowledge container. Commit messages use branch slug or PR number instead of issue #ID.
```

### External tracker support

When the team uses JIRA/Linear/etc.:
- The issue lives in the external tracker (e.g., `PROJ-123`)
- A corresponding GitHub issue may or may not exist
- If a GitHub issue exists, use its `#ID` for the ID-first convention
- If no GitHub issue exists, use the external ID in commits: `feat(PROJ-123): ...` and in the `--log` PR body as the reference
- Timeline comments, session-starts, discoveries, milestones — all go on the `--log` PR, never on the external tracker

### Mode detection pattern

Each slash command adds to its context block:

```markdown
- Shiplog mode: !`cat .shiplog/mode.md 2>/dev/null || echo "full"`
- Log branch exists: !`git branch --list "*--log" | head -1`
- Log PR: !`gh pr list --state open --search "[shiplog/worklog]" --json number,title --limit 1`
```

### Mode persistence

Persist mode in `.shiplog/mode.md` (a committed config file, like `.shiplog/routing.md`). This works across tools (Claude Code, Codex, Cursor) without relying on project memory which is tool-specific.

## Alternatives Considered

- **A: Remove quiet mode entirely** — Kills a real use case. The feature is well-designed, just not wired in.
- **B: Still create issues freely in quiet mode** — Defeats the purpose. A team that wants clean PRs also wants a clean issue tracker.
- **C: Shared reference file for mode logic** — Slash commands can't include shared files. The detection pattern is small enough to duplicate.

## Tasks

### Foundational: Quiet mode design fixes

- [ ] **T1: Define quiet mode issue policy in SKILL.md** `[tier-1]`
  - **What:** Replace the current Phase 1 quiet mode instruction ("defer capture") with the "attach, don't create" policy. Add the decision tree: if issue exists, attach; if not, ask user (create minimal issue or PR-only). Add external tracker support (JIRA/Linear/etc.) with external ID in commits. Update the ID-first convention table to show quiet mode uses external IDs or PR numbers when no GitHub issue exists.
  - **Files:** `skills/shiplog/SKILL.md` (modify)
  - **Why tier-1:** Requires design judgment about what "minimal issue" means, how external IDs interact with ID-first convention, and how PR-only mode changes the commit format.
  - **Accept when:** SKILL.md Phase 1 has explicit quiet mode issue policy with the decision tree. Phase 2, 3, 4, 5 reference it. ID-first naming table has quiet mode rows for external-tracker and PR-only scenarios.

- [ ] **T2: Add `.shiplog/mode.md` config and mode detection** `[tier-3]`
  - **What:** Define the `.shiplog/mode.md` config file format (like `.shiplog/routing.md`). Add first-activation prompt: "Full mode or Quiet mode?" Save choice to `.shiplog/mode.md`. Add mode detection to the SKILL.md mode selection section.
  - **Files:** `skills/shiplog/SKILL.md` (modify)
  - **Allowed to change:** Mode Selection section
  - **Must not change:** Mode descriptions (Full vs Quiet behavior)
  - **Decision budget:** `none`
  - **Accept when:** Mode is persisted in `.shiplog/mode.md`, detectable by slash commands via `cat .shiplog/mode.md`.

- [ ] **T3: Fix README claims that are false in quiet mode** `[tier-2]`
  - **What:** Rewrite claims that assume Full Mode is the only mode. The "What you get" section, "How it works" section, flow diagram, feature table, and slash command descriptions all need qualifying language or mode-conditional phrasing. Do NOT add "(Full Mode only)" disclaimers everywhere — instead rewrite the claims to be true in both modes. Example: "Every brainstorm becomes a GitHub Issue" becomes something like "Every brainstorm is captured — as a GitHub Issue, or in a knowledge branch your team never sees."
  - **Files:** `README.md` (modify)
  - **Decision budget:** narrow — must not change the marketing tone or add disclaimers. Rewrite to be true in both modes.
  - **Accept when:** Every claim in the README is accurate for both Full and Quiet mode. No `[Full Mode only]` disclaimers.

- [ ] **T4: Fix SKILL.md Core Principle** `[tier-2]`
  - **What:** Rewrite lines 12-14. The principle "Nothing gets lost" is true in both modes. But the specifics ("Every brainstorm becomes an issue. Every PR is a timeline.") are Full Mode only. Rewrite to be mode-agnostic: knowledge is always captured, but where it lives depends on mode.
  - **Files:** `skills/shiplog/SKILL.md` (modify)
  - **Decision budget:** narrow — principle must stay punchy and accurate.
  - **Accept when:** Core Principle is true in both modes.

### Critical: BROKEN slash commands

- [ ] **T5: Fix `/shiplog start` for quiet mode** `[tier-2]`
  - **What:** Add mode detection. When quiet mode: create `--log` branch + `--log` PR (per Phase 2 template), post session-start on `--log` PR instead of issue. If no GitHub issue exists (external tracker or PR-only), skip issue label transitions and use branch name or external ID.
  - **Files:** `commands/shiplog/start.md` (modify)
  - **Decision budget:** narrow
  - **Accept when:** In quiet mode, `/shiplog start` creates `--log` infrastructure and posts session-start on `--log` PR. Works with or without a GitHub issue.

- [ ] **T6: Fix `/shiplog commit` for quiet mode** `[tier-3]`
  - **What:** Add mode detection. When quiet mode: context comment targets `--log` PR. Commit format uses external ID if no GitHub issue.
  - **Files:** `commands/shiplog/commit.md` (modify)
  - **Decision budget:** `none`
  - **Accept when:** Context comment goes to `--log` PR in quiet mode.

- [ ] **T7: Fix `/shiplog pr` for quiet mode** `[tier-2]`
  - **What:** Add mode detection. When quiet mode: create clean feature PR (no timeline body, no `shiplog/history` label), post journey summary on `--log` PR. If no GitHub issue, omit `Closes #N`.
  - **Files:** `commands/shiplog/pr.md` (modify)
  - **Decision budget:** narrow
  - **Accept when:** Feature PR is clean in quiet mode. `--log` PR gets the summary.

- [ ] **T8: Fix `/shiplog resume` for quiet mode** `[tier-3]`
  - **What:** Add mode detection. When quiet mode: detect `--log` PR, post session-resume there. Load context from `--log` PR comments.
  - **Files:** `commands/shiplog/resume.md` (modify)
  - **Decision budget:** `none`
  - **Accept when:** Session-resume targets `--log` PR in quiet mode.

### Moderate: MISSING slash command features

- [ ] **T9: Fix `/shiplog plan` for quiet mode** `[tier-2]`
  - **What:** Add mode detection. When quiet mode: follow the "attach, don't create" policy. If no issue exists, ask user whether to create a minimal one or go PR-only. Do NOT create a `[shiplog/plan]`-labeled issue with full brainstorm prose. Save brainstorm content for the `--log` PR opening entry.
  - **Files:** `commands/shiplog/plan.md` (modify)
  - **Decision budget:** narrow — must implement the policy from T1
  - **Accept when:** In quiet mode, no `[shiplog/plan]` issue is created unless user explicitly asks. Brainstorm content is saved for `--log` PR.

- [ ] **T10: Fix `/shiplog hunt` for quiet mode** `[tier-3]`
  - **What:** Add mode detection. When quiet mode: separate `--log` worklog PRs from feature PRs in the report.
  - **Files:** `commands/shiplog/hunt.md` (modify)
  - **Decision budget:** `none`
  - **Accept when:** Worklog PRs appear in a separate section in quiet mode.

- [ ] **T11: Fix `/shiplog lookup` for quiet mode** `[tier-3]`
  - **What:** Add mode detection. When quiet mode: also search `--log` PR comments and bodies where knowledge lives.
  - **Files:** `commands/shiplog/lookup.md` (modify)
  - **Decision budget:** `none`
  - **Accept when:** Lookup results include `--log` PR thread hits in quiet mode.

### SKILL.md phase and reference file gaps

- [ ] **T12: Fix Phase 3 (Discovery) for quiet mode** `[tier-2]`
  - **What:** In quiet mode, discoveries should NOT create new issues by default (this is noise). Instead: log the discovery on the `--log` PR. If the discovery requires a stacked branch, create the branch but use the `--log` PR for tracking instead of a new issue. Only create an issue if the user explicitly asks or if a GitHub issue already exists for the discovery. Update both SKILL.md Phase 3 and `references/phase-templates.md`.
  - **Files:** `skills/shiplog/SKILL.md` (modify), `skills/shiplog/references/phase-templates.md` (modify)
  - **Decision budget:** narrow — must not lose discovery tracking, just redirect where it lives
  - **Accept when:** Phase 3 has explicit quiet mode path that avoids creating issues. Discovery content goes to `--log` PR.

- [ ] **T13: Fix Phase 5 partial delivery for quiet mode** `[tier-3]`
  - **What:** The partial delivery rules say "Post a `[shiplog/milestone]` comment on the issue." In quiet mode, post on `--log` PR instead.
  - **Files:** `skills/shiplog/SKILL.md` (modify)
  - **Decision budget:** `none`
  - **Accept when:** Partial delivery section has mode-conditional routing.

- [ ] **T14: Fix Phase 6 (Retrieval) for quiet mode** `[tier-3]`
  - **What:** Add instruction to search `--log` PR threads in quiet mode, since that's where knowledge lives. Currently only mentions issues, commits, and knowledge graph.
  - **Files:** `skills/shiplog/SKILL.md` (modify)
  - **Decision budget:** `none`
  - **Accept when:** Phase 6 mentions searching `--log` PR threads in quiet mode.

- [ ] **T15: Fix Phase 7 (Timeline) target specification** `[tier-3]`
  - **What:** Line 338 says "Add timeline comments" without specifying the target. Add: "on the issue (Full Mode) or `--log` PR (Quiet Mode)" — matching the Phase 4 pattern at line 292.
  - **Files:** `skills/shiplog/SKILL.md` (modify)
  - **Decision budget:** `none`
  - **Accept when:** Phase 7 has explicit mode-conditional target.

- [ ] **T16: Add quiet mode notes to reference files** `[tier-3]`
  - **What:** Add brief quiet mode notes to: (a) `references/closure-and-review.md` — review sign-offs go on the feature PR, not `--log` PR, since the feature PR is the merge artifact; (b) `references/verification-profiles.md` — verification evidence goes on `--log` PR; (c) `references/phase-templates.md` — add quiet mode templates for Phase 3 discovery and Phase 7 timeline comments.
  - **Files:** `skills/shiplog/references/closure-and-review.md` (modify), `skills/shiplog/references/verification-profiles.md` (modify), `skills/shiplog/references/phase-templates.md` (modify)
  - **Decision budget:** `none`
  - **Accept when:** Each file addresses quiet mode artifact routing.

### Edge cases and integration map

- [ ] **T17: Fix Integration Map for quiet mode** `[tier-3]`
  - **What:** The "Shiplog Adds" column says "Issue creation from output" (brainstorming) and "Timeline PR body template" (creating PRs). In quiet mode: brainstorming adds `--log` PR opening entry (not issue creation), and creating PRs adds clean feature PR (not timeline body). Add mode-conditional notes.
  - **Files:** `skills/shiplog/SKILL.md` (modify)
  - **Decision budget:** `none`
  - **Accept when:** Integration Map is accurate for both modes.

- [ ] **T18: Add quiet mode edge cases to SKILL.md** `[tier-3]`
  - **What:** Add edge cases: (a) slash command runs before `--log` PR exists — create it on the fly; (b) `--log` PR diverges beyond simple rebase — document recovery; (c) quiet mode selected but `--log` infrastructure never set up — detect and bootstrap; (d) no GitHub issue exists (external tracker) — how to detect and handle; (e) "offer to create a tracking issue" (line 375) and "offer retroactive issue creation" (line 377) — in quiet mode, offer `--log` PR instead.
  - **Files:** `skills/shiplog/SKILL.md` (modify)
  - **Decision budget:** `none`
  - **Accept when:** Edge Cases section covers all five quiet mode scenarios.

## Open Questions

- In PR-only mode (no issue at all), should commit messages use `feat(<branch-slug>):` or `feat(#<log-pr-number>):`? The `--log` PR number is a valid `#ID` for retrieval but it's not an issue.
- Should the `--log` PR body carry the task list in quiet mode when no issue exists? This would make it the single source of truth for plan + knowledge.

---
Authored-by: claude/opus-4.6 (claude-code)
Updated-by: claude/opus-4.6 (claude-code)
Edit-kind: rewrite
Edit-note: Deep audit revealed fundamental design tension — quiet mode issue creation is noise. Added "attach, don't create" policy, external tracker support, README claim fixes, and expanded from 11 to 18 tasks.
*Captain's log entry created by [shiplog](https://github.com/devallibus/shiplog)*

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[shiplog/plan] Quiet mode audit: slash commands and features are mode-unaware #128

Context

Design Summary

The surface problem: slash commands bypass SKILL.md

The fundamental problem: issues are noise too

README and SKILL.md claim mismatches

Approach

Quiet mode issue policy: "Attach, don't create"

External tracker support

Mode detection pattern

Mode persistence

Alternatives Considered

Tasks

Foundational: Quiet mode design fixes

Critical: BROKEN slash commands

Moderate: MISSING slash command features

SKILL.md phase and reference file gaps

Edge cases and integration map

Open Questions

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Location	Claim	Reality in Quiet Mode
SKILL.md line 14	"Every brainstorm becomes an issue"	Issues are noise; brainstorm goes in `--log` PR
SKILL.md line 14	"Every PR is a timeline of the entire journey"	Feature PR is clean; timeline is in `--log` PR
README line 30	"Every brainstorm becomes a GitHub Issue"	False
README line 35	"Every PR tells the full story"	False — only `--log` PR does
README line 37	"spin off a new issue"	Issues are noise
README line 45	"captures the result as a GitHub issue"	False
README line 51	"Design discussion becomes a GitHub Issue with tasks"	False
README line 55	"PR with full journey timeline"	False — feature PR is clean
README line 267	`/shiplog plan`: "capture it as a GitHub Issue"	False
README line 269	`/shiplog pr`: "Create a PR with a journey timeline body"	False — clean PR

[shiplog/plan] Quiet mode audit: slash commands and features are mode-unaware #128

Description

Context

Design Summary

The surface problem: slash commands bypass SKILL.md

The fundamental problem: issues are noise too

README and SKILL.md claim mismatches

Approach

Quiet mode issue policy: "Attach, don't create"

External tracker support

Mode detection pattern

Mode persistence

Alternatives Considered

Tasks

Foundational: Quiet mode design fixes

Critical: BROKEN slash commands

Moderate: MISSING slash command features

SKILL.md phase and reference file gaps

Edge cases and integration map

Open Questions

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions