orbital-command 0.1.0

package/templates/skills/scope-pre-review/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: scope-pre-review
+description: Reviews scope documents with full agent team analysis for comprehensive feedback. Use before implementing scopes, for thorough scope review, or when getting multiple perspectives.
+user-invocable: true
+agent-mode: team-review
+---
+
+# /scope-pre-review - Full Agent Team Analysis
+
+## What This Does
+
+Invokes the project's agent team to review a scope from all perspectives, applies fixes directly to the SPECIFICATION, then records findings in the AGENT REVIEW section for traceability.
+
+**Key principle**: After review, the SPECIFICATION must be a ready-to-execute contract. The implementer should never need to read AGENT REVIEW to know what to build.
+
+## Steps
+
+### Step 0: Record Session ID
+
+1. Run: `bash .claude/hooks/get-session-id.sh` — capture the UUID output
+2. Read the scope file's YAML frontmatter `sessions` field
+3. If `sessions:` key doesn't exist in frontmatter, add `sessions: {}` after `tags:`
+4. If the UUID is NOT already in `sessions.reviewScope`, append it (skip if duplicate)
+5. Write the updated frontmatter back to the scope file
+
+### Step 1: Load Scope Context
+
+Extract from the scope document:
+- **SPECIFICATION section** (primary context for agents)
+- **PROCESS Decisions & Uncertainties** (helps agents understand reasoning)
+- **Files Summary** (determines which agents to invoke)
+
+### Step 2: Determine Which Agents to Invoke
+
+Select agents based on `.claude/config/agent-triggers.json` and `orbital.config.json` agents configuration. The trigger file maps file patterns to the agents that should review changes in those areas.
+
+Read `.claude/config/agent-triggers.json` and match the scope's **Files Summary** against the configured patterns to determine which agents to launch.
+
+### Step 3: Launch Agent Team in Parallel
+
+**Launch all relevant agents in a SINGLE message with parallel Task tool calls.**
+
+Read each agent's spec first from `.claude/agents/`. Then launch with `subagent_type: "general-purpose"`:
+
+```
+Task: "Agent Review" — Include full SPECIFICATION section in prompt.
+Each agent reviews from their perspective and returns findings with severity.
+```
+
+### Step 4: Synthesize Findings with Dispositions
+
+Categorize agent findings into BLOCKERS / WARNINGS / SUGGESTIONS / VERIFIED OK (same as before). Then assign each finding a **disposition** that determines what happens next:
+
+| Disposition | When to Use | Applied to Spec? |
+|-------------|-------------|-------------------|
+| `APPLY` | Single clear fix, no ambiguity | Yes, automatically |
+| `CLARIFY` | Multiple valid resolution paths — user must choose | Yes, after user answers |
+| `NOTE` | Advisory guidance for the implementer, no spec change needed | No |
+
+**Classification rules:**
+
+- **BLOCKERS**: Default `APPLY`. Escalate to `CLARIFY` only when the blocker presents two or more valid approaches and the right choice depends on user preference or business context.
+- **WARNINGS**: `APPLY` when they identify a concrete spec gap (missing file, wrong type, missing constraint, incorrect architecture). `NOTE` when advisory ("keep additions minimal", "consider extracting if file grows").
+- **SUGGESTIONS**: Default `NOTE`. Promote to `APPLY` only when they fill an objective spec deficiency (e.g., missing shared component that multiple phases reference).
+
+**Resolve conflicts during synthesis** using a priority hierarchy appropriate to the project. Typical ordering:
+1. Security agents (security wins)
+2. Domain-critical agents (safety, financial, data integrity)
+3. Reliability agents (chaos, resilience)
+4. Domain experts (correctness)
+5. Architecture agents (patterns)
+6. UI/UX agents (aesthetics)
+
+### Step 5: Ask Clarifying Questions
+
+**After synthesis, before touching the spec** — collect all `CLARIFY` items and present them to the user as a batch. For each item:
+- State the problem clearly
+- List labeled options (A, B, etc.)
+- Provide a recommendation with reasoning
+
+Wait for user answers before proceeding.
+
+**If zero `CLARIFY` items, skip this step entirely.**
+
+Example format:
+
+```
+The review found N items that need your input before I update the spec:
+
+**[B-2] Service layer boundary violation**
+Module X has zero DB imports. Adding data lookup inside processRequest() breaks layer purity.
+
+  A) Push data resolution to callers — callers pass pre-resolved data into Module X (clean layers, slightly more caller code)
+  B) Create a thin middleware — wraps Module X calls, resolves data externally (more abstraction, new file)
+
+  Recommendation: A — matches existing caller-resolves pattern in the codebase
+
+**[W-4] Configuration source for feature Y**
+Feature Y uses a flat estimate, has no concept of dynamic configuration.
+
+  A) Use a config constant (e.g., CONFIG.FEATURE_Y.ESTIMATE)
+  B) Calculate from historical data
+
+  Recommendation: A — simpler, no query overhead
+
+Which options? (e.g., "B-2: A, W-4: A" or "agree" for all recommendations)
+```
+
+### Step 6: Apply Fixes to SPECIFICATION
+
+With all `APPLY` items and resolved `CLARIFY` items, systematically update the SPECIFICATION. The review is an authorized modification — no need to toggle `spec_locked`.
+
+**What to update, by section:**
+
+| Spec Subsection | Types of Changes |
+|-----------------|------------------|
+| **Requirements (Must Have)** | Add missing requirements identified by blockers. Update text to incorporate fixes. |
+| **Requirements (Nice to Have)** | Promote to Must Have if a blocker requires the item. |
+| **Requirements (Out of Scope)** | Add items explicitly excluded by review decisions. |
+| **Technical Approach** | Fix architectural errors (e.g., tier violations). Update diagrams/data flows. Document resolved design decisions. |
+| **Implementation Phases — Files** | Add missing files (test files, schema.sql, etc.). Remove invalid files. Update file descriptions. |
+| **Implementation Phases — Changes** | Update change descriptions to incorporate fixes. Add new change items for blocker-identified work. |
+| **Files Summary** | Add/remove/update rows to match phase file changes. |
+| **Success Criteria** | Add criteria for significant blocker fixes. |
+| **Risk Assessment** | Add new risks identified by agents. Update mitigations. |
+| **Definition of Done** | Add items for significant new requirements. |
+
+**Do NOT modify**: DASHBOARD (status updates are Step 8), PROCESS (implementation working memory), AGENT REVIEW (written separately in Step 7).
+
+**Add a DEVIATION NOTE** inside the SPECIFICATION HTML comment block:
+
+```html
+<!--
+DEVIATION NOTE (YYYY-MM-DD): Spec updated by /scope-pre-review to address
+N blockers and M warnings. Key changes: [2-3 word summary per major change].
+See AGENT REVIEW section for full traceability.
+-->
+```
+
+### Step 7: Write AGENT REVIEW Section
+
+Write findings to the **AGENT REVIEW** section with the same synthesis format, plus a summary header and **Resolution** lines for traceability:
+
+```markdown
+### Review Status
+- **Requested**: [agent-list]
+- **Completed**: [agent-list]
+- **Date**: YYYY-MM-DD
+
+### Spec Changes Applied
+N blockers and M warnings applied directly to the SPECIFICATION.
+K items resolved via user clarification.
+J items are implementation notes (no spec change).
+
+### Synthesis
+
+**BLOCKERS** (must fix before implementation):
+
+- [B-1] Description (Source: Agent, Severity)
+  **Resolution**: APPLIED — [one-line summary of what changed in the spec]
+
+- [B-2] Description (Source: Agent, Severity)
+  **Resolution**: APPLIED (user chose Option A) — [one-line summary]
+
+- [B-3] Description (Source: Agent)
+  **Resolution**: NOTE — [why no spec change: advisory guidance, implementation detail, etc.]
+
+**WARNINGS** (should fix):
+
+- [W-1] Description (Source: Agent)
+  **Resolution**: APPLIED — [what changed]
+
+- [W-2] Description (Source: Agent)
+  **Resolution**: NOTE — implementation guidance for the executor
+
+**SUGGESTIONS** (nice to have):
+
+- [S-1] Description (Source: Agent)
+  **Resolution**: NOTE — optional enhancement, not applied to spec
+
+- [S-2] Description (Source: Agent)
+  **Resolution**: APPLIED — [what changed]
+
+**VERIFIED OK**:
+- [Points agents confirmed are correct]
+```
+
+### Step 8: Update Scope Status
+
+After applying spec fixes and writing the AGENT REVIEW:
+- Update frontmatter: `status: backlog`, `spec_locked: true`
+- Move file: `mv scopes/planning/{file} scopes/backlog/`
+- Update DASHBOARD Quick Status: `🟢 **Status**: Backlog | **Spec Locked**: Yes`
+- Add to Recent Activity: `Review completed — N blockers, M warnings. X items applied to spec, K clarifications resolved.`
+
+### Step 9: Signal Completion
+
+Emit the agent completion event so the Orbital Command dashboard turns off the progress indicator:
+
+```bash
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"team_review"}' --scope "{NNN}"
+```
+
+## Modes
+
+| Command | What Runs |
+|---------|-----------|
+| `/scope-pre-review` | All relevant agents based on files |
+| `/scope-pre-review security` | Red team only (security + resilience agents) |
+| `/scope-pre-review domain` | Blue team only (domain experts) |
+| `/scope-pre-review full` | ALL agents regardless of files |

package/templates/skills/scope-verify/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: scope-verify
+description: Formal review gate that checks spec compliance, session separation, and test gate results before allowing completion. Use when a scope is in review state and ready for formal verification.
+user-invocable: true
+---
+
+# /scope-verify NNN — Formal Review Gate
+
+Runs a comprehensive review of a scope before it can be marked as completed. This is the **only** path to completion — the implementing session cannot complete its own work.
+
+## Prerequisites
+
+- Scope must be in `scopes/implementing/` (primary) or `scopes/review/` (re-runs)
+- Scope must have `sessions.implementScope` recorded (implementation happened)
+- Current session must be **different** from the implementing session
+
+## Workflow
+
+### Step 0: Record Session ID
+
+1. Run: `bash .claude/hooks/get-session-id.sh` — capture the UUID output
+2. Read the scope file's YAML frontmatter `sessions` field
+3. If `sessions:` key doesn't exist in frontmatter, add `sessions: {}` after `tags:`
+4. If the UUID is NOT already in `sessions.reviewGate`, append it (skip if duplicate)
+5. Write the updated frontmatter back to the scope file
+
+### Step 1: Validate Preconditions
+
+1. Find the scope file: `scopes/implementing/*{NNN}*.md` (primary) or `scopes/review/*{NNN}*.md` (re-runs)
+   - If not found in either directory, error: "Scope NNN not found."
+2. Read frontmatter — verify `status: implementing` or `status: review`
+3. Read `sessions.implementScope` — must exist and be non-empty
+4. **Session separation**: Compare current session UUID with ALL UUIDs in `sessions.implementScope`
+   - If current UUID appears in `implementScope` → **BLOCK**:
+     ```
+     Session separation violation: You implemented this scope.
+        A different session must run the review gate.
+        Start a new Claude Code session and run: /scope-post-review NNN
+     ```
+
+### Step 2: Check Test Gate Results
+
+Before proceeding, verify that `/test-checks` and `/test-code-review` have been run. This skill does NOT embed the full test suite itself — it checks whether test results already exist.
+
+1. Check for recent test gate results (e.g., gate reports from Orbital Command, or recent passing test output in the session)
+2. If no test results exist, **BLOCK**:
+   ```
+   Test gate results not found. Run /test-checks and /test-code-review first,
+   then re-run /scope-post-review NNN.
+   ```
+3. If test results exist but contain failures, **BLOCK** and report the failures.
+
+### Step 3: Scope-Specific Checks
+
+Run 3 checks that the test gates don't cover:
+
+#### 3a. Spec Compliance (Agent Judgment)
+
+1. Read the scope's **SPECIFICATION** section (Part 2):
+   - Requirements (Must Have, Nice to Have)
+   - Implementation Phases
+   - Success Criteria
+   - Definition of Done
+2. Read `baseCommit` from scope frontmatter (set when scope entered implementing)
+   - If `baseCommit` exists: `git diff ${baseCommit}...HEAD -- $(list files from scope's Files Summary table)`
+   - If `baseCommit` missing and `WORKFLOW_BRANCHING_MODE=worktree`: `git diff main...HEAD -- $(list files)`
+   - If `baseCommit` missing and trunk mode: `git diff HEAD~10...HEAD -- $(list files)` (heuristic fallback)
+3. Cross-reference each "Must Have" requirement against the actual changes
+4. Verify each Success Criteria item is addressed
+5. **Verdict**: PASS if all Must Have requirements and Success Criteria are addressed, FAIL otherwise
+6. **Evidence**: List each requirement and whether it was found in the diff
+
+#### 3b. No Follow-on Work (Agent Judgment)
+
+1. Read the scope's **PROCESS** section (Part 3):
+   - Check "Deviations from Spec" for any items marked as deferred
+   - Check Implementation Log for TODOs or "will do later" language
+2. Read the scope's **AGENT REVIEW** section:
+   - Check for unresolved BLOCKERs
+3. Read the scope's **DASHBOARD** section:
+   - Check all phases are marked `✅ Done`
+   - Check for incomplete Next Actions
+4. **Verdict**: PASS if no deferred work is found, FAIL otherwise
+5. **Evidence**: List any deferred items found (or "No deferred items, 0 unresolved blockers")
+
+#### 3c. Project-Specific Validation (Machine-Verifiable)
+
+Run any project-specific validation commands from `orbital.config.json`:
+- Run `commands.validateTemplates` (if configured, skip if null)
+- Run `commands.validateDocs` (if configured, skip if null)
+- Run `commands.checkRules` (if configured, skip if null)
+
+1. If no project-specific commands are configured → **PASS** with evidence "No project-specific validations configured"
+2. If commands are configured:
+   - Run each non-null command
+   - **Verdict**: PASS if all configured commands succeed, FAIL otherwise
+3. **Evidence**: List commands run and their results
+
+### Step 4: Write Verdict File
+
+Write the verdict to `.claude/review-verdicts/{NNN}.json`:
+
+```json
+{
+  "scopeId": NNN,
+  "verdict": "PASS|FAIL",
+  "reviewSession": "<current-session-uuid>",
+  "implementSession": "<first-uuid-from-sessions.implementScope>",
+  "reviewedAt": "<ISO-8601-timestamp>",
+  "criteria": {
+    "test_gates": {
+      "verdict": "PASS|FAIL",
+      "evidence": "<summary of /test-checks and /test-code-review results>"
+    },
+    "spec_compliance": {
+      "verdict": "PASS|FAIL",
+      "evidence": "<list of requirements checked>"
+    },
+    "no_followon_work": {
+      "verdict": "PASS|FAIL",
+      "evidence": "<deferred items or 'none found'>"
+    },
+    "project_validation": {
+      "verdict": "PASS|FAIL",
+      "evidence": "<validation status>"
+    }
+  }
+}
+```
+
+Overall verdict is PASS only if ALL 4 criteria are PASS.
+
+### Step 5: Update Scope
+
+1. Update the scope's **AGENT REVIEW** section with a review gate summary:
+   ```markdown
+   ### Review Gate — YYYY-MM-DD
+   - **Verdict**: PASS/FAIL
+   - **Session**: <uuid>
+   - **test_gates**: PASS/FAIL — <evidence>
+   - **spec_compliance**: PASS/FAIL — <evidence>
+   - **no_followon_work**: PASS/FAIL — <evidence>
+   - **project_validation**: PASS/FAIL — <evidence>
+   ```
+
+### Step 6: Scope Transition (on PASS only)
+
+If all criteria passed:
+1. Move scope file: `mv scopes/implementing/{file} scopes/review/` (or leave in place if already in `scopes/review/`)
+2. Update frontmatter: `status: review`
+3. Update DASHBOARD: `✅ **Status**: Reviewed | Ready to Commit`
+
+### Step 7: Report & Next Steps
+
+**If any FAIL**:
+```
+╔═══════════════════════════════════════════════════════════════╗
+║  ❌ REVIEW GATE FAILED — Scope NNN                          ║
+╠═══════════════════════════════════════════════════════════════╣
+║  Failed criteria:                                            ║
+║  • spec_compliance: [evidence]                               ║
+║  • no_followon_work: [evidence]                              ║
+║                                                              ║
+║  Fix the issues, then re-run: /scope-post-review NNN              ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+Scope stays in `scopes/implementing/` on failure.
+
+Then emit the FAIL event and stop:
+```bash
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","verdict":"FAIL"}' --scope "{NNN}"
+```
+
+**If all PASS**:
+```
+╔═══════════════════════════════════════════════════════════════╗
+║  ✅ REVIEW GATE PASSED — Scope NNN                          ║
+╠═══════════════════════════════════════════════════════════════╣
+║  All 4 criteria passed. Verdict written to:                  ║
+║  .claude/review-verdicts/NNN.json                            ║
+║                                                              ║
+║  Scope moved to review. Ready to commit.                     ║
+║  Next: /git-commit to commit.                                ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+Then emit the success event:
+```bash
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","verdict":"PASS"}' --scope "{NNN}"
+```
+
+**Do NOT auto-chain** into `/scope complete` or `/git-commit`. The next step is manual.
+
+## Important Notes
+
+- The verdict file is the **only** artifact that unlocks committing via `/git-commit`
+- The `review-gate-check.sh` hook enforces this at the Edit tool level
+- Re-running the review gate overwrites the previous verdict file
+- Session separation is enforced at both skill level (Step 1) and hook level
+- On PASS, the scope moves to `scopes/review/` — `/git-commit` handles the next transition

package/templates/skills/session-init/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: session-init
+description: Initializes work session context by loading project state and recent history. Use at session start, when beginning work, or when context needs refreshing.
+user-invocable: true
+---
+
+# /session-init - Re-Initialize Session Context
+
+---
+tokens: ~200
+trigger: /session-init
+purpose: Re-display session initialization and reload critical context
+---
+
+## What This Does
+
+Re-shows the session initialization banner and reloads awareness of the enforcement system. Use when:
+- You've been working a while and need a reset
+- Agent seems to have forgotten the rules
+- Starting a new logical task within the same session
+
+## Steps
+
+1. **Display the initialization banner:**
+
+```
+══════════════════════════════════════════════════════════════════════════════
+SESSION RE-INITIALIZED
+══════════════════════════════════════════════════════════════════════════════
+
+Before writing ANY code, you MUST:
+
+1. IDENTIFY TASK TYPE & USE THE MATCHING SKILL:
+   Check .claude/skills/ for available workflow skills.
+   Common patterns:
+   ┌────────────────────┬─────────────────────┐
+   │ Task               │ Invoke First        │
+   ├────────────────────┼─────────────────────┤
+   │ Plan feature       │ /scope-create       │
+   │ Implement scope    │ /scope-implement    │
+   │ Review scope       │ /scope-verify       │
+   │ Commit work        │ /git-commit         │
+   └────────────────────┴─────────────────────┘
+
+2. STATE WHAT YOU READ before proceeding:
+   "I have read [specific files] and am ready to proceed."
+
+══════════════════════════════════════════════════════════════════════════════
+PROJECT RULES:
+══════════════════════════════════════════════════════════════════════════════
+
+   Read .claude/orbital.config.json for project-specific rules
+   and enforcement configuration.
+
+══════════════════════════════════════════════════════════════════════════════
+BEFORE EVERY COMMIT: Run /test-checks
+══════════════════════════════════════════════════════════════════════════════
+```
+
+2. **Confirm readiness:**
+
+   State: "Session re-initialized. Ready to proceed with proper workflow."

package/templates/skills/session-resume/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: session-resume
+description: Resumes previous work session by loading saved context and progress. Use when continuing previous work, picking up where left off, or restoring session state.
+user-invocable: true
+---
+
+# /session-resume - Session Resumption
+
+Reconstruct context and pick up where you left off.
+
+---
+
+## What This Skill Does
+
+Quickly rebuilds context after interruption:
+
+1. **Check git status** - Uncommitted work
+2. **Check recent commits** - What was done
+3. **Check scope docs** - In-progress scopes
+4. **Check TODOs** - Pending markers in code
+5. **Reconstruct state** - "Where were we?"
+6. **Identify next steps** - What to do next
+
+---
+
+## When to Use
+
+- After context compaction
+- Starting new session with in-progress work
+- Returning after a break
+- "Where were we?"
+
+---
+
+## Trigger Phrases
+
+This skill should be suggested when user says:
+- "Where were we?"
+- "What was I working on?"
+- "Resume"
+- "Continue where we left off"
+- "Pick up from before"
+
+---
+
+## Auto-Trigger Contexts
+
+This skill should be **automatically suggested** when:
+- Session starts with uncommitted changes in git
+- After context compaction (detected by system)
+- Conversation starts with implicit continuation
+
+---
+
+## Execution
+
+### Step 1: Check Git Status
+
+```bash
+# Uncommitted changes
+git status --short
+
+# Recent commits (last 5)
+git log --oneline -5
+
+# Current branch
+git branch --show-current
+```
+
+**Parse results:**
+```markdown
+### Git Context
+
+**Branch**: `feature/scope-012-refactor`
+**Uncommitted changes**: 8 files modified
+**Recent commits**:
+- `abc1234` feat: Add auth middleware (2 hours ago)
+- `def5678` refactor: Extract helper functions (3 hours ago)
+```
+
+### Step 2: Check Scope Documents
+
+```bash
+# Find in-progress scopes
+grep -l "Status:.*In Progress\|Status:.*in_progress" scopes/*.md
+
+# Check most recent scope
+ls -t scopes/*.md | head -1
+```
+
+**Parse scope status:**
+```markdown
+### Active Scope
+
+**Scope**: 012-service-refactor
+**Status**: In Progress
+**Current Phase**: Phase 2 - Extract Helpers
+**Completed**: Phase 1
+**Remaining**: Phase 2 (in progress), Phase 3, Phase 4
+```
+
+### Step 3: Check for TODOs
+
+```bash
+# TODO markers in recently modified files
+git diff --name-only HEAD~5 | xargs grep -n "TODO\|FIXME\|XXX" 2>/dev/null
+
+# Or in uncommitted changes
+git diff --name-only | xargs grep -n "TODO\|FIXME" 2>/dev/null
+```
+
+### Step 4: Generate Resume Report
+
+```markdown
+## Session Resume Report
+
+### Quick Summary
+You were working on **Scope 012: Service Refactor**.
+Last activity was **2 hours ago**.
+
+### Current State
+
+**Branch**: `feature/scope-012-refactor`
+
+**Uncommitted Work**:
+- `src/utils/helpers.ts` - New file (extracted helpers)
+- `src/services/manager.ts` - Modified (imports updated)
+
+**Scope Progress**:
+| Phase | Status |
+|-------|--------|
+| Phase 1: Extract types | Complete |
+| Phase 2: Extract helpers | In Progress |
+| Phase 3: Integrate changes | Pending |
+
+**TODOs Found**:
+- `helpers.ts:45`: `// TODO: Add error handling`
+
+### Recommended Next Steps
+
+1. **Complete Phase 2**: Finish extracting queue helpers
+2. **Fix TODO**: Add error handling in helpers.ts:45
+3. **Run tests**: Verify nothing is broken
+4. **Commit checkpoint**: Save progress before Phase 3
+```
+
+### Step 5: Offer Actions
+
+After presenting the resume report, offer:
+- "Continue with [next phase]?"
+- "Should I run `/test-checks` first to verify state?"
+- "Would you like me to explain what was being worked on?"
+
+---
+
+## Output Format
+
+```markdown
+## 🔄 Session Resume
+
+### Context Restored
+[1-2 sentence summary of where we are]
+
+### Work in Progress
+| Item | Status | Files |
+|------|--------|-------|
+| [task] | [status] | [files] |
+
+### Last Actions
+- [Recent commit 1]
+- [Recent commit 2]
+
+### Pending Items
+- [ ] [Item 1]
+- [ ] [Item 2]
+
+### Suggested Next Step
+[Recommended action]
+```
+
+---
+
+## Integration with Scope Documents
+
+If a scope is in progress, extract:
+- Current phase name and status
+- Checklist items completed/remaining
+- Team review findings (if present)
+- Blockers identified
+
+This makes the scope document the **single source of truth** for resumption.
+
+---
+
+## Tips
+
+- **Check uncommitted first** - Most important context
+- **Recent > old** - Focus on last few hours of work
+- **Be specific** - Name files, line numbers, phases
+- **Suggest action** - Don't just report, recommend next step
+- **Link to scope** - If scope exists, reference it