sync

• IF command exits non-zero → capture stderr, print diagnostic, then retry or fallback:

  ✗ {command} failed: {stderr summary}
    → Try: {suggested fix}
    → Fallback: {what the skill does instead}

• IF command returns empty stdout when a result is expected → treat as ⚠ warn, note it, proceed with fallback
• Never stop the entire skill for a single command failure — degrade gracefully and skip the affected section </context>

0. Parse Arguments & Validate Environment

• IF empty or "full" → MODE=full
• IF "quick" → MODE=quick
• IF "--consolidate" → MODE=consolidate
• IF unrecognized → show usage and stop: "Usage: /product:sync [quick|full|--consolidate]"

• Run

  git rev-parse --is-inside-work-tree 2>&1

• IF exit code non-zero → stop: "✗ Not inside a git repo. Run

  git init

  or cd into your project."
• Run

  git remote -v 2>/dev/null

  → store HAS_REMOTE (true if any remote configured)

• Run

  linear auth whoami 2>&1

• IF command not found → set LINEAR_AVAILABLE=false, warn:

  ✗ linear CLI not found
    → Try: Install from https://github.com/schpet/linear-cli
    → Fallback: Running git-only sync (Linear checks will be skipped)

• ELIF output contains "not authenticated" or "unauthorized" or exit code non-zero → set LINEAR_AVAILABLE=false, warn:

  ✗ linear CLI not authenticated
    → Try: Run `linear auth` to log in
    → Fallback: Running git-only sync (Linear checks will be skipped)

• ELSE → LINEAR_AVAILABLE=true

• IF

  .linear-project

  exists:
  • Read file and trim whitespace/newlines:

    PROJECT=$(cat .linear-project | tr -d '\n' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')

  • IF trimmed value is empty → warn: "

    .linear-project

    exists but is empty. Continuing unscoped."
  • ELIF LINEAR_AVAILABLE:
    • Validate project exists:

      linear project list 2>&1 | grep -qi "$PROJECT"

    • IF not found → warn:

      ⚠ Project '{PROJECT}' not found in Linear. It may have been renamed or archived.
        → Try: Update `.linear-project` or run `/product:init-project` to relink
        → Fallback: Continuing unscoped (showing all projects)

      Set PROJECT="" (clear it)
    • ELSE → note: "Scoped to Linear project: {PROJECT}"
  • Build PROJECT_FLAG:

    ${PROJECT:+--project '$PROJECT'}

• IF

  .linear-project

  missing → warn: "No

  .linear-project

  found — showing issues from all projects. Run

  /product:init-project

  to link one."

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 PRODUCT ► SYNC [{PROJECT or "All Projects"}] ({MODE})
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Gather State

• linear issue list -s started --limit 20 $PROJECT_FLAG 2>&1

  → in-progress issues
  • IF fails → warn and set STARTED_ISSUES=empty

• linear issue list -s unstarted --limit 20 $PROJECT_FLAG 2>&1

  → backlog
  • IF fails → warn and set BACKLOG_ISSUES=empty

• linear issue list -s completed --limit 10 $PROJECT_FLAG 2>&1

  → recently completed
  • IF fails → warn and set COMPLETED_ISSUES=empty

• linear issue list -s cancelled --limit 10 $PROJECT_FLAG 2>&1

  → recently cancelled (for orphan detection)
  • IF fails → warn and set CANCELLED_ISSUES=empty

• git log --oneline -30 2>&1

  → recent commits
  • IF repo has no commits → note "Empty repo, no commits yet" and skip git-based gap detection

• git log --oneline --first-parent main -30 2>/dev/null || git log --oneline --first-parent master -30 2>/dev/null

  → commits on default branch only (for squash-merge detection)
  • IF fails (no main/master) → skip squash-merge detection, note which default branch was tried

• git branch --list 2>&1

  → local branches

• git branch -r --merged main 2>/dev/null || git branch -r --merged master 2>/dev/null

  → remote branches merged into default (only if HAS_REMOTE)

• git reflog --since="7 days ago" --no-decorate 2>/dev/null | head -50

  → detect force-pushes/rebases
• Current branch name:

  git branch --show-current 2>&1

• Read

  .planning/STATE.md

  for current phase context
• Read

  .planning/ROADMAP.md

  for phase list and completion status
• Read

  .planning/PROJECT.md

  for project objectives
• IF any file missing → skip silently (GSD is optional)

2. Detect Gaps

git log --first-parent

ENG-\d+

• Synced: For each in-progress Linear issue, check if a local branch contains the issue ID (e.g.,

  eng-123

  in branch name) AND has commits within the last 48h referencing it.
• Stale in Linear: In-progress issues where

  git log --all --oneline --since="48 hours ago" | grep -i "$ISSUE_ID"

  returns empty.
• Untracked work:

  git log --oneline -30 | grep -oiE '[A-Z]+-[0-9]+'

  extracts issue IDs from recent commits, cross-reference against Linear unstarted list.
• Done but open: Check

  git branch --merged main

  (or master) for branches containing issue IDs that are still "Started" in Linear. Also check first-parent log for squash-merge references.
• Orphan branch: Extract issue IDs from branch names (

  git branch --list | grep -oiE '[a-z]+-[0-9]+'

  ), check against cancelled/done issues list.
• Missing branch: In-progress Linear issues where no local branch contains the issue ID.
• Squash-merged: Issue IDs found in

  git log --first-parent main --oneline

  that are still "Started" in Linear but have no open feature branch.
• Rebased/force-pushed: Parse

  git reflog

  for lines containing "rebase" or "reset" on branches that match active issue IDs. Flag as informational.
• Direct-to-main: Issue IDs in default branch commits that have no corresponding branch in

  git branch --list

  .
• Unassigned in-progress: From Linear data, check started issues for missing assignee field (parse

  linear issue list

  output).

3. Consolidate Objectives

• Run

  linear project view "$PROJECT" 2>&1

  → extract milestones, description, target dates
• IF command fails or project not set → note "Linear project metadata unavailable" and skip this source

• Read

  .planning/ROADMAP.md

  → extract phase names and completion status
• Read

  .planning/PROJECT.md

  → extract stated objectives and timeline
• IF files missing → note "GSD planning state unavailable" and skip this source

• Read

  CLAUDE.md

  → extract any goals, objectives, or project description sections
• IF missing → skip this source

• Does every Linear milestone have a corresponding GSD phase?
• Does CLAUDE.md mention goals not tracked in Linear or GSD?
• Are there GSD phases with no matching Linear milestone (future work is okay)?

Objective Alignment:
─────────────────────
  ✓ "Auth system" — Linear milestone ↔ GSD Phase 3 ↔ CLAUDE.md
  ⚠ "API redesign" — Linear milestone, no GSD phase planned
  ⚠ "Performance audit" — In CLAUDE.md goals, not in Linear
  ○ "Onboarding flow" — GSD Phase 5, no Linear milestone (future work)

• Create Linear issues for untracked objectives
• Update CLAUDE.md to match current Linear state
• Note them and move on (address later)
• Skip — alignment is fine as-is

4. Present Summary

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 SYNC REPORT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Synced (N):
  ✓ ENG-123 — Feature description

Gaps Found (N):
  ⚠ ENG-456 — Stale: in-progress but no commits in 3 days
  ⚠ ENG-789 — Untracked: commits exist but Linear shows unstarted
  ⚠ ENG-012 — Done but open: branch merged, issue still in-progress
  ⚠ ENG-345 — Squash-merged: appears on main, still marked Started
  ○ ENG-678 — Direct-to-main: commits on main, no feature branch
  ○ ENG-901 — Unassigned: in-progress but no assignee
  ○ eng-999-old-feature — Rebased: force-push detected (informational)

Backlog (N):
  ○ ENG-234 — Urgent — Unstarted
  ○ ENG-567 — High — Unstarted

{IF consolidation ran:}
Objective Alignment:
  ✓ N aligned  ⚠ N misaligned  ○ N untracked

5. Resolve Gaps (Interactive)

• Still working on it → keep as-is
• Blocked → add a blocker comment to Linear:

  linear issue comment add $ID -b "Blocked: {reason}" 2>&1

• Abandoned → move back to backlog:

  linear issue update $ID -s "Triage" 2>&1

• Actually done → move to Done:

  linear issue update $ID -s "Done" 2>&1

• Yes, move to In Progress:

  linear issue update $ID -s "In Progress" 2>&1

• Yes, it's actually Done:

  linear issue update $ID -s "Done" 2>&1

• No, those commits were reverted → skip

• Yes, move to Done with auto-generated summary:

  linear issue update $ID -s "Done" 2>&1

• No, there's still remaining work → skip

eng-999-old-feature

• Delete the branch:

  git branch -d $BRANCH 2>&1

  (safe delete; if fails, note it may have unmerged work and ask about

  -D

  )
• Keep it → skip

• Create one now →

  git checkout -b $BRANCH_NAME 2>&1

  (generate slug from issue title)
• It's on a different machine → skip
• It's done, just not tracked → move to Done

• Yes, move to Done with merge reference
• No, there's still remaining work on another branch

• Move to Done (work is on main)
• Ignore (was a hotfix, already tracked)

• Yes, assign to me:

  linear issue update $ID --assignee me 2>&1

• Assign to someone else → prompt for name
• Move back to backlog:

  linear issue update $ID -s "Triage" 2>&1

• No action needed unless user asks

✗ Failed to update ENG-XXX: {stderr}
  → Try: Run the command manually: linear issue update ...

6. Cleanup & Route

Cleanup (ask before each action)

• List branches from "Orphan branch" gaps that user agreed to delete
• Also check for any local branches already merged into default branch:

  git branch --merged main 2>/dev/null | grep -v 'main\|master\|\*'

• Ask: "Found N merged/orphan branches. Delete them all, pick which to delete, or skip?"

• From the gathered Linear data, check for issues with very similar titles (compare words, look for near-duplicates)
• IF potential duplicates found → "These issues might be duplicates:"

  ⚠ ENG-111 "Login page redesign" ↔ ENG-222 "Redesign login page"

  "Merge them in Linear? (This just flags them — you'll need to merge manually in Linear)"
• IF none → skip silently

• Check for stale remote tracking branches:

  git remote prune origin --dry-run 2>&1

• IF stale refs found → ask: "Found N stale remote refs. Prune them?"
  • Yes →

    git remote prune origin 2>&1

  • No → skip

Route to Next Action

• IF consolidation found misalignment → suggest

  /product:update

  for a full project status review
• IF there are unstarted high/urgent issues → suggest

  /product:start-task

• IF there's an active in-progress issue with no branch → suggest creating one
• IF GSD state exists with an incomplete phase → suggest

  /gsd:progress

• IF many gaps were found and resolved → suggest running

  /product:sync

  again to verify, or

  /product:maintain

  for a deeper health check
• IF everything is synced and nothing urgent → "All clear. Pick up the next task when ready."

• Environment validated with explicit error messages for every failure mode
• Linear CLI auth checked (not just existence) — graceful fallback if unavailable

• .linear-project

  trimmed, validated against Linear, special chars handled
• All 10 gap categories detected (or skipped gracefully with reason)
• Squash-merged and direct-to-main work correctly identified
• Objectives consolidated across Linear, GSD, and CLAUDE.md (in full/consolidate mode)
• Every gap surfaced and user made an explicit decision
• All Linear update commands have exit code checking
• Cleanup offered: stale branches, duplicate issues, remote ref pruning
• Clear next action suggested based on final state </success_criteria>