---
phase: 35.3-psyche-sync-setup-ux-pass-error-display-doctor-partial-docs
plan: 04
type: execute
wave: 1
depends_on: []
files_modified:
  - plugin/spt/skills/psyche-sync-setup/SKILL.md
autonomous: true
requirements: [SYNC-DOC-EXIT1-01, SYNC-DOC-RECOVERY-01]
must_haves:
  truths:
    - "(D-02) SKILL.md's 'Interpret the exit code' list documents exit code 1 (generic accept_flow failure) and tells the skill layer to surface the now-human-readable error line and offer `$OWL doctor`."
    - "(D-08) SKILL.md has an inline recovery subsection ordered: (a) re-run setup (idempotent), (b) `$OWL doctor` to inspect partial state, (c) `--disable` escape hatch + re-setup, with a one-line `seed/`-inspect + manual rebase last-resort POINTER only."
  artifacts:
    - path: "plugin/spt/skills/psyche-sync-setup/SKILL.md"
      provides: "Exit-1 bullet + inline recovery subsection"
      contains: "**1**"
  key_links: []
---

<objective>
Resolve Issue 5 (SYNC-DOC-EXIT1-01) and Issue 3 (SYNC-DOC-RECOVERY-01), both
doc-only, both inline in the skill the operator already invokes (D-02, D-08):
(1) add a `**1**` bullet to the "Interpret the exit code" list (currently
0/5/2/3/4); (2) add a minimal inline recovery subsection, ordered per D-08, with
the `seed/`/manual-rebase last resort as a one-line pointer ONLY — Phase 35.2's
per-ref dispatcher output obsoletes the old `git update-ref` workaround.

Purpose: An operator hitting exit 1 has a documented interpretation and a short,
ordered recovery path — no fragmented sibling doc/ADR.
Output: Two edits to one SKILL.md (no code, no rebuild needed; deploys via the
standard all-files DEPLOY.ps1 sync to the plugin cache).
</objective>

<execution_context>
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
@$HOME/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/35.3-psyche-sync-setup-ux-pass-error-display-doctor-partial-docs/35.3-CONTEXT.md
@.planning/phases/35.3-psyche-sync-setup-ux-pass-error-display-doctor-partial-docs/35.3-RESEARCH.md

<interfaces>
<!-- Extracted from SKILL.md — executor needs no exploration. -->

From plugin/spt/skills/psyche-sync-setup/SKILL.md:
- "Interpret the exit code:" list (lines 88-103) currently has bullets for **0**, **5**, **2 / 3 / 4** — NO **1** bullet. Insert **1** logically (e.g. after **0**, before **5**).
- "## Already enabled?" at line 105, "## To disable" at line 116 (documents `--disable` → state=failing reason=user-disabled), "## Caveats" at line 127.
- The recovery subsection slots near "## To disable" / "## Caveats" (RESEARCH: under or between them).
- Phase 35.2 per-ref dispatcher status tags (for the recovery pointer context): PUSHED / RECONCILED / DIVERGED / PUSH_FAILED / PROBE_FAILED (CLAUDE.md §Conventions). These now report per-ref outcomes, so manual `git update-ref`-against-bare-repo recovery is obsolete — mention `seed/` inspect + manual rebase as a one-line last resort only.

D-02 exit-1 bullet intent (phrase, not verbatim-locked): generic `accept_flow`
failure; the binary now prints a human-readable error line (Plan 01); surface
that line to the user and offer to run `$OWL doctor` for diagnostics.

D-08 recovery ordering (LOCKED): (a) re-run /spt:psyche-sync-setup — idempotent,
safe (D-13); (b) `$OWL doctor` — inspects partial state (now surfaces the Plan 03
partial-setup Warn row); (c) `$OWL psyche-sync-setup --disable` escape hatch then
re-setup; then a SINGLE one-line last-resort pointer to inspecting `seed/` +
manual `git rebase` — NOT a full procedure.
</interfaces>
</context>

<tasks>

<task type="auto">
  <name>Task 1: Add exit-code 1 bullet to the interpret-exit-code list</name>
  <files>plugin/spt/skills/psyche-sync-setup/SKILL.md</files>
  <read_first>
    - plugin/spt/skills/psyche-sync-setup/SKILL.md (lines 85-103 — the invocation block + "Interpret the exit code:" list with bullets 0/5/2-3-4)
  </read_first>
  <action>
    In plugin/spt/skills/psyche-sync-setup/SKILL.md, add a `**1**` bullet to the "Interpret the exit code:" list (per D-02). Place it after the **0** bullet and before **5** so codes read in a sensible order. Wording: exit 1 is the generic `accept_flow` setup failure; the binary prints a human-readable error line (no longer a Debug struct — Plan 01); instruct the skill layer to surface that error line to the user and offer to run `$OWL doctor` for diagnostics, then point at the Recovery subsection (Task 2). Match the existing bullet style/voice in that list. Do NOT alter the 0/5/2/3/4 bullets.
  </action>
  <verify>
    <automated>Select-String -Path plugin/spt/skills/psyche-sync-setup/SKILL.md -Pattern '^\s*-\s+\*\*1\*\*'</automated>
  </verify>
  <acceptance_criteria>
    - Grep `^\s*-\s+\*\*1\*\*` against SKILL.md returns exactly one match within the "Interpret the exit code" list.
    - The bullet mentions `$OWL doctor`.
    - The 0/5/2/3/4 bullets are byte-unchanged.
  </acceptance_criteria>
  <done>Exit code 1 is documented in the skill's exit-code contract with an actionable instruction and a doctor pointer.</done>
</task>

<task type="auto">
  <name>Task 2: Add inline Recovery subsection (D-08 ordered, minimal + pointer)</name>
  <files>plugin/spt/skills/psyche-sync-setup/SKILL.md</files>
  <read_first>
    - plugin/spt/skills/psyche-sync-setup/SKILL.md (lines 105-137 — "## Already enabled?", "## To disable", "## Caveats" sections, to find the insertion point and match heading style)
  </read_first>
  <action>
    In plugin/spt/skills/psyche-sync-setup/SKILL.md, add a `## Recovery` (or `## Recovering from a failed setup`) subsection — placed near "## To disable" / "## Caveats" — INLINE in this skill (D-08, no sibling doc/ADR). Content ordered EXACTLY: (a) re-run `/spt:psyche-sync-setup` — idempotent and safe (D-13), converges partial state; (b) run `$OWL doctor` to inspect partial state (now surfaces the partial-setup Warn row from Plan 03); (c) `$OWL psyche-sync-setup --disable` escape hatch, then re-run setup to re-enable. Close with a SINGLE one-line last-resort POINTER: if divergence persists, inspect `seed/` under the spt runtime root and resolve manually with `git rebase` — note that Phase 35.2's per-ref dispatcher tags (PUSHED/RECONCILED/DIVERGED/PUSH_FAILED/PROBE_FAILED) make this rare and that the old `git update-ref`-against-bare-repo workaround is obsolete. Keep depth minimal + pointer (D-08) — do NOT write a full manual-rebase procedure. Match SKILL.md heading + prose style.
  </action>
  <verify>
    <automated>Select-String -Path plugin/spt/skills/psyche-sync-setup/SKILL.md -Pattern '(?i)## Recover'</automated>
  </verify>
  <acceptance_criteria>
    - SKILL.md contains a Recovery heading (`## Recover...`).
    - The subsection contains, in order, references to: re-run setup / idempotent, `$OWL doctor`, `--disable`, and a single `seed/` + `rebase` last-resort line.
    - No full step-by-step rebase procedure (last resort is one line / pointer only — D-08).
    - "## To disable" and "## Caveats" sections remain present and unbroken.
  </acceptance_criteria>
  <done>An inline, minimal, D-08-ordered recovery subsection exists in SKILL.md with the manual-rebase path as a one-line pointer only.</done>
</task>

</tasks>

<threat_model>
## Trust Boundaries

| Boundary | Description |
|----------|-------------|
| skill doc → operator/Claude reading instructions | Doc text only; no executable surface, no input parsing |

## STRIDE Threat Register

| Threat ID | Category | Component | Disposition | Mitigation Plan |
|-----------|----------|-----------|-------------|-----------------|
| T-35.3-08 | Information Disclosure | recovery doc suggesting destructive git ops | accept | Last-resort manual `rebase`/`seed/` inspection is a one-line pointer (D-08), not a copy-paste destructive command; ordered safe paths (re-run, doctor, --disable) come first. Low risk — operator-driven, recoverable steps prioritized. |
| T-35.3-09 | Tampering | SKILL.md edit not reaching plugin cache | mitigate | Deploy via `docs/DEPLOY.ps1` (full all-files sync per project memory); never hand-edit `~/.claude/plugins/cache/cplugs/spt/` (RESEARCH Pitfall 4). |
| T-35.3-SC | Tampering | npm/pip/cargo installs | mitigate | Doc-only plan; no installs, no deps, no rebuild. Audit N/A per RESEARCH "Package Legitimacy Audit: Not applicable". |
</threat_model>

<verification>
- Grep confirms the `**1**` exit-code bullet and the `## Recover...` subsection exist with the required references.
- Visual read confirms D-08 ordering and that the last-resort is a single pointer line, not a procedure.
- SKILL.md change reaches the plugin cache only via `docs/DEPLOY.ps1` (deploy is end-of-phase/milestone per CLAUDE.md cadence — not this plan's responsibility, but note it in SUMMARY).
</verification>

<success_criteria>
- SYNC-DOC-EXIT1-01: exit 1 documented in the skill's exit-code list.
- SYNC-DOC-RECOVERY-01: inline minimal recovery subsection, D-08-ordered, manual rebase = one-line pointer.
- No code change, no rebuild; single SKILL.md touched.
</success_criteria>

<output>
Create `.planning/phases/35.3-psyche-sync-setup-ux-pass-error-display-doctor-partial-docs/35.3-04-SUMMARY.md` when done.
</output>