sequant 1.20.2 → 2.0.0

package/templates/skills/assess/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: assess
-description: "Issue triage and status assessment - analyze current state and recommend next workflow phase."
+description: "Issue triage and status assessment - analyze current state, detect health signals, and recommend next action with full workflow plan."
 license: MIT
 metadata:
   author: sequant
-  version: "1.0"
+  version: "3.0"
 allowed-tools:
   - Read
   - Glob
@@ -13,462 +13,464 @@ allowed-tools:
   - Bash(gh *)
 ---
 
-# Issue Assessment & Triage
+# Unified Issue Assessment & Triage
 
 You are the "Assessment Agent" for the current repository.
 
 ## Purpose
 
-When invoked as `/assess`, your job is to:
+When invoked as `/assess <issue-numbers>`, your job is to:
 
-1. Analyze the current state of a GitHub issue
-2. Determine what phase it's in (planning, implementation, QA, complete, blocked)
-3. Detect what artifacts exist (plan comments, branches, PRs, worktrees)
-4. Identify blockers, missing information, or staleness
-5. Show AC coverage status if applicable
-6. **Recommend** the next appropriate slash command (but don't execute it)
+1. Gather issue context (GitHub, git, codebase)
+2. Run health checks to surface red flags
+3. Recommend exactly ONE action per issue from a fixed vocabulary
+4. Output a scannable dashboard (batch) or focused summary (single)
+5. Provide copy-pasteable CLI commands for actionable issues
 
-## Behavior
+**This command is read-only** — it analyzes and recommends but never takes action.
 
-Invocation:
+## Invocation
 
-- `/assess 123`:
-  - Treat `123` as the GitHub issue number
-  - Fetch issue details, comments, and related artifacts
-- `/assess <description>`:
-  - Treat the text as context about what to assess
+- `/assess 123` — Assess a single issue (detailed mode)
+- `/assess 152 153 154` — Assess multiple issues (dashboard mode)
+- `/solve 123` — Alias for `/assess` (deprecated, will show notice)
 
-### When to Use This Command
+## Fixed Action Vocabulary
 
-**Good use cases:**
-- Picking up an unfamiliar issue ("What's the status of #147?")
-- Resuming work after days/weeks away ("Where did I leave off?")
-- Handoff scenarios ("What did the previous dev complete?")
-- Daily triage ("Which issues are ready for next steps?")
-- Debugging stalled issues ("Why isn't this progressing?")
+Every issue gets exactly ONE action:
 
-**Not needed for:**
-- Active work on an issue you just touched (you know the state)
-- Simple "implement this feature" requests (just use `/spec` → `/exec`)
-- Issues where the next step is obvious
+| Action | When |
+|--------|------|
+| **PROCEED** | Clear requirements, codebase matches, no blockers |
+| **CLOSE** | Resolved by another PR, duplicate, outdated |
+| **MERGE** | Two issues cover 70%+ same scope |
+| **REWRITE** | Existing PR/branch too stale, needs fresh start |
+| **CLARIFY** | No ACs, ambiguous requirements, unresolved questions |
+| **PARK** | Blocked on dependency, deferred, not automatable |
 
 ## Assessment Process
 
-### 1. Issue Context Gathering
+### Step 1: Context Gathering
 
-Collect information about the issue:
+**From GitHub (parallel for all issues):**
 
-**From GitHub:**
+```bash
+gh issue view <N> --json title,body,labels,state,comments,assignees
+```
 
-- Issue title, body, labels, status
+- Title, body, labels, status, all comments
 - Acceptance Criteria (explicit or inferred)
-- **All comments** (read every comment to gather complete context):
-  - Look for plan drafts, progress updates, QA reviews
-  - Comments often contain clarifications, updates, or additional AC added after the initial issue description
-  - Review discussion about implementation details, edge cases, or requirements mentioned in comments
-  - Check for feedback from previous review cycles or iterations
 - Last activity timestamp
-- Assigned developer(s)
 
-**From Git:**
-- Check if branch exists: `git branch -a | grep <issue-number>`
-- Check if worktree exists: `git worktree list | grep <issue-number>`
-- Check for related PRs: `gh pr list --search "in:title <issue-number>"`
-- If branch exists, check commit history: `git log --oneline feature/<issue-number>*`
+**From Git (parallel):**
+
+```bash
+git branch -a | grep <N> || true
+git worktree list | grep <N> || true
+gh pr list --search "<N> in:title" --json number,title,state,headRefName,mergeable || true
+```
+
+- If branch exists: `git log --oneline main..<branch>`
+- If PR exists: `gh pr view <pr> --json state,mergedAt,mergeable,commits`
 
 **From Codebase:**
 
-- Look for TODOs mentioning the issue using the Grep tool: `Grep(pattern="TODO.*#<issue-number>")`
-- Check for test files related to the feature
-- Identify modified files (if branch exists)
+- Grep for TODOs: `Grep(pattern="TODO.*#<N>")`
+- Check files referenced in issue body exist
+- Identify modified files if branch exists
+
+### Step 2: Health Checks
 
-### 2. Phase Detection
+Surface red flags. Only track signals that change the recommendation.
 
-Determine the current phase:
+| Signal | Detection | Implication |
+|--------|-----------|-------------|
+| Referenced files don't exist | Glob/Grep | Issue may be outdated → CLOSE |
+| PR has merge conflicts | `gh pr view` | Needs rebase → REWRITE |
+| PR 100+ commits behind | `git rev-list --count` | Likely needs fresh start → REWRITE |
+| Another issue covers same scope | Compare open issues | Consider → MERGE |
+| Duplicate of closed issue | Compare recently closed | → CLOSE |
+| No ACs, vague requirements | Issue body analysis | → CLARIFY |
+| Open questions unanswered | Comment thread | → CLARIFY |
+| Blocked on another issue | Body/comments mention deps | → PARK |
+| No activity 14+ days | Timestamps | Flag as stale (warning only) |
+| Stale worktree/branch from merged PR | Worktree list + PR state | → Cleanup annotation |
 
-**Planning Phase** - Issue needs a plan:
+### Step 3: Action Selection
 
-- No plan comment exists
-- AC are unclear or missing
-- No technical approach documented
-- **Indicators:** Issue just opened, labeled "needs planning", no detailed comments
+**Decision tree (priority order):**
+1. No ACs, vague requirements → **CLARIFY**
+2. Blocked on dependency → **PARK**
+3. Resolved by another PR → **CLOSE**
+4. 70%+ overlap with open issue → **MERGE**
+5. PR 100+ commits behind or files diverged → **REWRITE**
+6. Clear requirements, codebase matches → **PROCEED**
 
-**Implementation Phase** - Issue is being coded:
+### Step 4: Workflow Detection (PROCEED/REWRITE only)
 
-- Plan exists (in comments or inferred)
-- Branch/worktree exists with commits
-- Some AC partially met
-- **Indicators:** Branch exists, recent commits, labeled "in progress"
+**Phase selection from labels:**
 
-**QA Phase** - Implementation complete, needs review:
-- Branch has commits
-- Developer claims implementation complete
-- No QA review exists yet
-- **Indicators:** PR open, labeled "ready for review", implementation comment exists
+| Labels | Workflow |
+|--------|----------|
+| bug, fix, hotfix, patch | `exec → qa` |
+| docs, documentation, readme | `exec → qa` |
+| ui, frontend, admin, web, browser | `spec → exec → test → qa` |
+| security, auth, authentication, permissions | `spec → security-review → exec → qa` |
+| complex, refactor, breaking, major | `spec → exec → qa` + `-q` |
+| enhancement, feature (default) | `spec → exec → qa` |
 
-**Blocked Phase** - Issue is stuck:
-- No activity for 7+ days
-- Open questions in comments
-- Dependency on another issue
-- **Indicators:** Labeled "blocked", comments mention blockers, stale
+**Valid phases (from `PhaseSchema` in `src/lib/workflow/types.ts`):** `spec`, `security-review`, `exec`, `testgen`, `test`, `verify`, `qa`, `loop`, `merger`
 
-**Complete Phase** - Issue is done:
-- PR merged
-- AC all met (based on QA review)
-- Issue closed
-- **Indicators:** Closed, PR merged, labeled "completed"
+**Skip spec when:** bug/docs label, OR spec comment already exists on issue.
 
-**Unclear Phase** - Can't determine state:
-- Insufficient information
-- Conflicting indicators
-- **Action:** Request clarification
+**Resume detection:** Branch exists with commits ahead of main → mark as resume (`◂`).
 
-### 3. Artifact Detection
+**PR review detection:** Open PR with implementation complete → mark as review-needed (`◂ qa`).
 
-List what exists:
+**Quality loop (`-q`):** Recommend for everything except simple bug fixes and docs-only.
 
-**Planning Artifacts:**
-- [ ] AC checklist in issue or comments
-- [ ] Implementation plan (phases/steps)
-- [ ] Architecture decisions documented
-- [ ] Open questions identified
+**Other flags:**
+- `--chain` — Chain issues: each branches from previous (implies --sequential)
+- `--qa-gate` — Pause chain on QA failure, preventing downstream issues from building on broken code (requires --chain)
+- `--base <branch>` — Issue references a feature branch
 
-**Implementation Artifacts:**
-- [ ] Feature branch: `feature/<issue-number>-<slug>`
-- [ ] Worktree: `../worktrees/feature/<branch-name>/`
-- [ ] Commits on branch: X commits since branching
-- [ ] Modified files: [list key files]
-- [ ] Tests written: [test file paths]
+### Step 5: Conflict Detection
 
-**QA Artifacts:**
-- [ ] PR open: #<pr-number>
-- [ ] QA review comment exists
-- [ ] Test results: [passing/failing]
-- [ ] Build status: [passing/failing]
+```bash
+git worktree list --porcelain 2>/dev/null | grep "^worktree" | cut -d' ' -f2 || true
+```
 
-**Blockers/Issues:**
-- [ ] Open questions in comments
-- [ ] Failed tests or build
-- [ ] Dependency on issue #<other-issue>
-- [ ] Missing resources or access
-- [ ] Stale (no activity in X days)
+For each active worktree, check `git diff --name-only main...HEAD` for file overlap with assessed issues.
 
-### 4. AC Coverage Analysis
+---
 
-If AC exist, assess coverage:
+## Output Format
 
-**For each AC item:**
-- `MET` - Evidence suggests complete
-- `IN_PROGRESS` - Partially implemented
-- `NOT_STARTED` - No evidence of work
-- `UNCLEAR` - Can't determine from available info
+### Batch Mode (2+ issues)
 
-**Example:**
-```
-AC Coverage:
-- AC-1: Display fact-check queue in admin panel - MET
-- AC-2: Allow editors to approve/reject items - IN_PROGRESS
-- AC-3: Send email notifications on approval - NOT_STARTED
-- AC-4: Log all actions in audit log - UNCLEAR (no audit log visible)
+**Design principle:** Dashboard first. Copy-pasteable commands. Silence means healthy.
 
-Coverage: 1/4 complete, 1/4 in progress, 1/4 not started, 1/4 unclear
+```
+ #    Action     Reason                              Run
+<N>   <ACTION>   <short reason>                       <workflow or symbol>
+<N>   <ACTION>   <short reason>                       <workflow or symbol>
+...
+────────────────────────────────────────────────────────────────
+
+╭──────────────────────────────────────────────────────────────╮
+│  npx sequant run <N1> <N2> <flags>                           │
+│  npx sequant run <N3> <flags>              # resume          │
+╰──────────────────────────────────────────────────────────────╯
+
+────────────────────────────────────────────────────────────────
+Order: <N> → <N> (<shared file>) · <N> → <N> (<dependency>)
+
+⚠ #<N>  <warning>
+⚠ #<N>  <warning>
+────────────────────────────────────────────────────────────────
+Cleanup:
+  <executable command>                 # reason
+  <executable command>                 # reason
+────────────────────────────────────────────────────────────────
+
+<!-- For posting to individual issues, use standard marker format: -->
+<!-- assess:action=<ACTION> -->
+<!-- assess:phases=<csv> -->
+<!-- assess:quality-loop=<bool> -->
 ```
 
-### 5. Staleness Check
-
-Flag if issue is stale:
+#### Run Column Symbols
 
-- **Fresh:** Activity within 3 days
-- **Aging:** 3-7 days since last activity
-- **Stale:** 7-14 days since last activity
-- **Abandoned:** 14+ days since last activity
+| Symbol | Meaning | Example |
+|--------|---------|---------|
+| `spec → exec → qa` | Full workflow | Standard feature |
+| `exec → qa` | Skip spec | Bug, docs, or spec exists |
+| `◂ exec → qa` | Resume existing work | Branch has commits |
+| `◂ qa` | PR needs review/QA | Open PR, impl done |
+| `⟳ spec → exec → qa` | Restart (fresh) | Stale PR abandoned |
+| `→ #N` | Merge into target | Overlapping issue |
+| `?` | Needs info first | Missing ACs |
+| `‖` | Blocked/deferred | Dependency or manual |
+| `—` | No action needed | Already closed/merged |
 
-For stale/abandoned issues, identify:
-- Last actor (who touched it last)
-- Last action type (commit, comment, label change)
-- Likely cause of staleness (blocked, low priority, forgotten)
+#### Command Block Rules
 
-## Output Structure
+1. Only PROCEED and REWRITE issues get commands
+2. Group by identical phases + flags → same line
+3. Resume issues get `# resume` comment
+4. Rewrite issues get `# restart` comment
+5. Chain mode issues use `--chain` flag
+6. If ALL issues share the same workflow, emit a single command
 
-Produce a structured assessment:
+#### Annotation Rules
 
-### Issue Summary
-- **Issue:** #123 - <title>
-- **Status:** <Open|Closed> | <labels>
-- **Last Activity:** X days ago (<timestamp>)
-- **Phase:** <Planning|Implementation|QA|Blocked|Complete|Unclear>
+- **`Order:`** — Only when sequencing matters (shared files or dependencies). Format: `A → B (reason)` joined by ` · `
+- **`⚠` warnings** — Only non-obvious signals (complexity, staleness, dual concerns). One line each. Prefix with issue number.
+- **`Cleanup:`** — Only when actionable (stale branches, merged-but-open issues, label changes). Show as executable commands with `# reason` comments.
+- **Omit entire section** (including its separator) when no annotations of that type exist.
+- **"All clear" is silence** — no annotation means no issues.
 
-### Acceptance Criteria
-- AC-1: ... [MET|IN_PROGRESS|NOT_STARTED|UNCLEAR]
-- AC-2: ... [MET|IN_PROGRESS|NOT_STARTED|UNCLEAR]
-- ...
-- **Coverage:** X/Y complete
+#### Batch Example (mixed states)
 
-(If AC don't exist or are unclear, note: "AC not clearly defined")
+```
+ #    Action     Reason                              Run
+ 462  PARK       Manual measurement task              ‖
+ 461  PROCEED    Exact label matching                  exec → qa
+ 460  PROCEED    batch-executor tests                  exec → qa
+ 458  PROCEED    Parallel UX + race condition          spec → exec → qa
+ 447  CLOSE      PR #457 merged                        —
+ 443  PROCEED    Consolidate gh calls                  spec → exec → qa
+ 412  PROCEED    Auth token refresh                    ◂ exec → qa
+ 405  REWRITE    PR #380 200+ commits behind           ⟳ spec → exec → qa
+────────────────────────────────────────────────────────────────
+
+╭──────────────────────────────────────────────────────────────╮
+│  npx sequant run 461 460 -q --phases exec,qa                      │
+│  npx sequant run 458 443 -q                                  │
+│  npx sequant run 412 -q --phases exec,qa     # resume        │
+│  npx sequant run 405 -q                      # restart       │
+╰──────────────────────────────────────────────────────────────╯
+
+────────────────────────────────────────────────────────────────
+Order: 460 → 461 (batch-executor.ts)
+
+⚠ #458  Dual concern (UX + race) across 4 files
+⚠ #405  Stale 30+ days, ACs still valid
+────────────────────────────────────────────────────────────────
+Cleanup:
+  git worktree remove .../447-...      # merged, stale worktree
+  gh issue close 447                   # PR #457 merged
+  gh issue edit 461 --add-label cli    # missing label
+────────────────────────────────────────────────────────────────
+
+<!-- #462 assess:action=PARK -->
+<!-- #461 assess:action=PROCEED assess:phases=exec,qa assess:quality-loop=true -->
+<!-- #460 assess:action=PROCEED assess:phases=exec,qa assess:quality-loop=true -->
+<!-- #458 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
+<!-- #447 assess:action=CLOSE -->
+<!-- #443 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
+<!-- #412 assess:action=PROCEED assess:phases=exec,qa assess:quality-loop=true -->
+<!-- #405 assess:action=REWRITE assess:phases=spec,exec,qa assess:quality-loop=true -->
+```
 
-### Artifacts Found
-**Planning:**
-- [x] Plan comment in issue #<comment-id>
-- [ ] Architecture decisions documented
+#### Batch Example (all clean)
 
-**Implementation:**
-- [x] Branch: `feature/123-issue-slug` (5 commits)
-- [x] Worktree: `../worktrees/feature/123-issue-slug/`
-- [x] Modified files: `components/admin/FactCheckQueue.tsx`, `lib/queries/fact-checks.ts`
-- [ ] Tests written
+When every issue is PROCEED with no warnings, the output is minimal:
 
-**QA:**
-- [ ] PR open
-- [ ] QA review complete
+```
+ #    Action     Reason                              Run
+ 461  PROCEED    Exact label matching                  exec → qa
+ 460  PROCEED    batch-executor tests                  exec → qa
+ 443  PROCEED    Consolidate gh calls                  spec → exec → qa
+────────────────────────────────────────────────────────────────
+
+╭──────────────────────────────────────────────────────────────╮
+│  npx sequant run 461 460 -q --phases exec,qa                      │
+│  npx sequant run 443 -q                                      │
+╰──────────────────────────────────────────────────────────────╯
+
+────────────────────────────────────────────────────────────────
+
+<!-- #461 assess:action=PROCEED assess:phases=exec,qa assess:quality-loop=true -->
+<!-- #460 assess:action=PROCEED assess:phases=exec,qa assess:quality-loop=true -->
+<!-- #443 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
+```
 
-### Blockers & Issues
-- [ ] None identified
-- [x] Stale (10 days since last commit)
-- [x] Missing tests
-- [ ] Depends on issue #<other>
+---
 
-### Label Review
+### Single Mode (1 issue)
 
-Analyze current labels vs issue content and suggest updates when mismatches are detected:
+More context since you're focused on one issue. Separators between every section.
 
-**Current Labels:** `enhancement`, `admin`
-**Suggested Labels:** `enhancement`, `admin`, `refactor`
-**Reason:** Issue body mentions structural changes across multiple files
-**Quality Loop Impact:** Will auto-enable due to `refactor` label
+#### PROCEED
 
-**Suggested Action:**
-```bash
-gh issue edit <N> --add-label refactor
 ```
+#<N> — <Title>
+<State> · <labels>
+────────────────────────────────────────────────────────────────
 
-**Label Detection Hints:**
-- `refactor` - Keywords: "refactor", "restructure", "reorganize", "cleanup", "migration"
-- `complex` - Keywords: "complex", "major", "large-scale", "breaking"
-- `ui`/`frontend` - Keywords: "component", "UI", "page", "form", "button", "modal"
-- `backend` - Keywords: "API", "database", "query", "server", "endpoint"
-- `cli` - Keywords: "command", "CLI", "script", "terminal"
-- `docs` - Keywords: "documentation", "README", "guide", "tutorial"
-- `security` - Keywords: "auth", "permission", "vulnerability", "secret", "token"
-- `bug` - Keywords: "fix", "broken", "error", "crash", "doesn't work"
-
-**When to Suggest Label Updates:**
-- Issue body contains keywords not reflected in current labels
-- Complexity dropdown selection doesn't match actual labels
-- Quality loop would benefit from additional labels (complex/refactor/breaking)
-- Area dropdown selection doesn't match current labels (ui/backend/cli/docs)
+→ PROCEED — <one-line reason>
 
-### Recommendation
+╭──────────────────────────────────────────────────────────────╮
+│  npx sequant run <N> <flags>                                 │
+╰──────────────────────────────────────────────────────────────╯
 
-Based on the assessment, recommend one of:
+<phases> · <N> ACs · <flag reasoning>
+────────────────────────────────────────────────────────────────
+⚠ <warning if any>
+⚠ Conflict: #<N> also modifies <path>
+────────────────────────────────────────────────────────────────
 
-**If Phase = Planning:**
-```
-RECOMMENDATION: Run `/spec 123`
-- Issue needs a clear plan and AC before implementation
-- This will establish AC checklist and technical approach
+<!-- assess:action=PROCEED -->
+<!-- assess:phases=<csv> -->
+<!-- assess:quality-loop=<bool> -->
 ```
 
-**If Phase = Implementation (not started):**
-```
-RECOMMENDATION: Run `/exec 123`
-- Plan exists and AC are clear
-- Ready to begin implementation
-- This will create feature worktree and start coding
+If no warnings exist, omit the warning section and its separator:
+
 ```
+#458 — Parallel run UX freeze + reconcileState race condition
+Open · bug, enhancement, cli
+────────────────────────────────────────────────────────────────
+
+→ PROCEED — Both root causes confirmed in codebase
 
-**If Phase = Implementation (in progress):**
+╭──────────────────────────────────────────────────────────────╮
+│  npx sequant run 458 -q                                      │
+╰──────────────────────────────────────────────────────────────╯
+
+spec → exec → qa · 8 ACs · -q (dual concern)
+────────────────────────────────────────────────────────────────
+
+<!-- assess:action=PROCEED -->
+<!-- assess:phases=spec,exec,qa -->
+<!-- assess:quality-loop=true -->
 ```
-RECOMMENDATION: Continue `/exec 123`
-- Implementation is underway (5 commits on branch)
-- Worktree exists at: ../worktrees/feature/123-issue-slug/
-- AC coverage: 1/4 complete, 2/4 in progress
-- Navigate to worktree and continue implementation
+
+#### CLOSE
+
 ```
+#<N> — <Title>
+<State> · <labels>
+────────────────────────────────────────────────────────────────
+
+→ CLOSE — <reason with evidence>
+────────────────────────────────────────────────────────────────
+Cleanup:
+  <executable commands>                # reason
+────────────────────────────────────────────────────────────────
 
-**If Phase = QA:**
+<!-- assess:action=CLOSE -->
 ```
-RECOMMENDATION: Run `/qa 123`
-- Implementation appears complete
-- Branch has 12 commits, last commit 2 days ago
-- No QA review exists yet
-- Review code and validate against AC
+
+#### CLARIFY
+
 ```
+#<N> — <Title>
+<State> · <labels>
+────────────────────────────────────────────────────────────────
 
-**If Phase = Blocked:**
+→ CLARIFY — <what's missing>
+
+Need: <specific information required>
+  <details about why this blocks work>
+────────────────────────────────────────────────────────────────
+
+<!-- assess:action=CLARIFY -->
 ```
-RECOMMENDATION: Resolve blockers first
-- Issue depends on #145 (not yet merged)
-- Open question in comments: "Should we use email or in-app notifications?"
-- Suggest: Review #145 status, clarify notification approach with team
-- Once unblocked, run `/exec 123` to continue
+
+#### PARK
+
 ```
+#<N> — <Title>
+<State> · <labels>
+────────────────────────────────────────────────────────────────
+
+→ PARK — <reason>
+  Resume after: <condition>
+────────────────────────────────────────────────────────────────
 
-**If Phase = Complete:**
+<!-- assess:action=PARK -->
 ```
-RECOMMENDATION: No action needed
-- PR #156 merged 3 days ago
-- All AC met (per QA review)
-- Issue can be closed
+
+#### MERGE
+
 ```
+#<N> — <Title>
+<State> · <labels>
+────────────────────────────────────────────────────────────────
+
+→ MERGE → #<target> — <overlap description>
+  This issue: <scope summary>
+  Target:     <scope summary>
+────────────────────────────────────────────────────────────────
 
-**If Phase = Unclear:**
+<!-- assess:action=MERGE -->
 ```
-RECOMMENDATION: Gather more information
-- Unable to determine current state
-- Missing information: [list what's unclear]
-- Suggest: Review issue comments, check with team, or run `/spec 123` to establish baseline
+
+#### REWRITE
+
 ```
+#<N> — <Title>
+<State> · <labels>
+────────────────────────────────────────────────────────────────
 
-### Context for Next Command
+→ REWRITE — <reason>
 
-Provide relevant context to help the next command:
+╭──────────────────────────────────────────────────────────────╮
+│  npx sequant run <N> <flags>                 # fresh start   │
+╰──────────────────────────────────────────────────────────────╯
 
-**Key Files to Review:**
-- List the main components/files involved
-- Point to relevant data layer code
-- Reference architecture documentation if exists
+<phases> · <N> ACs
+────────────────────────────────────────────────────────────────
+⚠ <stale/diverged details>
+────────────────────────────────────────────────────────────────
 
-**Similar Patterns:**
-- Reference similar features in the codebase
-- Point to reusable patterns
+<!-- assess:action=REWRITE -->
+<!-- assess:phases=<csv> -->
+<!-- assess:quality-loop=<bool> -->
+```
 
-**Potential Risks:**
-- Identify any error handling gaps
-- Note external integrations not yet tested
-- Flag potential database migrations needed
+---
 
-## Examples
+## Section Visibility Rules
 
-### Example 1: Fresh Issue Needs Planning
+| Section | Show when |
+|---------|-----------|
+| Command block | At least one PROCEED or REWRITE issue |
+| `Order:` | File conflicts or dependencies require sequencing |
+| `⚠` warnings | Non-obvious signals exist |
+| `Cleanup:` | Stale branches, merged-but-open issues, or label changes |
+| Separators | Between sections that are both shown; omit if adjacent section is omitted |
 
-```
-Issue Summary
-- Issue: #147 - Add fact-check queue to admin panel
-- Status: Open | needs-planning, admin
-- Last Activity: 2 hours ago
-- Phase: Planning
-
-Acceptance Criteria
-AC not clearly defined in issue
-Inferred AC from description:
-- Display pending fact-check items in queue
-- Allow approval/rejection actions
-- Send notifications on status change
-
-Artifacts Found
-Planning: None
-Implementation: None
-QA: None
-
-Blockers & Issues
-- [ ] No blockers
-
-Recommendation
-RECOMMENDATION: Run `/spec 147`
-- Issue is fresh but lacks detailed AC and plan
-- Need to establish clear requirements before implementation
-```
+Every separator and section is conditional. If there are no warnings and no cleanup, the output is just: table → separator → command block → separator → markers.
 
-### Example 2: Implementation In Progress, Stale
+---
 
-```
-Issue Summary
-- Issue: #145 - Fix data validation edge cases
-- Status: Open | in-progress, bug
-- Last Activity: 10 days ago
-- Phase: Implementation (Stale)
-
-Acceptance Criteria
-- AC-1: Handle basic validation - MET
-- AC-2: Handle edge cases (empty, null, special chars) - IN_PROGRESS
-- AC-3: Add validation tests - NOT_STARTED
-Coverage: 1/3 complete
-
-Artifacts Found
-Implementation:
-- [x] Branch: feature/145-validation-fixes (3 commits)
-- [x] Worktree: ../worktrees/feature/145-validation-fixes/
-- [x] Modified: lib/utils/validation.ts
-- [ ] Tests not found
-
-Blockers & Issues
-- [x] Stale (10 days since last commit)
-- [x] Missing tests
-- [ ] No known blockers
-
-Recommendation
-RECOMMENDATION: Resume `/exec 145`
-- Implementation is 1/3 complete but stale
-- Worktree still exists, resume work there
-- Focus on AC-2 (edge cases) and AC-3 (tests)
-- Add tests before considering complete
-```
+## State Tracking
 
-### Example 3: Ready for QA
+Initialize state for each assessed issue:
 
-```
-Issue Summary
-- Issue: #148 - Add bulk publishing to content updates
-- Status: Open | ready-for-review
-- Last Activity: 1 day ago
-- Phase: QA
-
-Acceptance Criteria
-- AC-1: Multi-select in content updates list - UNCLEAR
-- AC-2: Bulk publish action button - UNCLEAR
-- AC-3: Confirmation dialog - UNCLEAR
-- AC-4: Success/error feedback - UNCLEAR
-Coverage: Unclear (need QA review to validate)
-
-Artifacts Found
-Implementation:
-- [x] Branch: feature/148-bulk-publishing (15 commits)
-- [x] Modified: components/admin/news/ContentUpdatesList.tsx, lib/admin/bulk-actions.ts
-- [x] Tests: __tests__/bulk-publishing.test.ts
-QA:
-- [ ] No PR yet
-- [ ] No QA review
-
-Blockers & Issues
-- [ ] No blockers
-- Developer marked as "ready for review" in last comment
-
-Recommendation
-RECOMMENDATION: Run `/qa 148`
-- Implementation appears complete (15 commits, tests added)
-- Developer believes AC are met
-- Need QA review to validate and assess A+ status
-- Create PR if not exists, review code and test against AC
+```bash
+TITLE=$(gh issue view <N> --json title -q '.title')
+npx tsx scripts/state/update.ts init <N> "$TITLE"
 ```
 
-## Meta-Assessment
+Note: `/assess` only initializes issues — actual phase tracking happens during workflow execution.
 
-After providing the assessment, briefly note:
+## Persist Analysis
 
-- **Confidence Level:** How certain are you about the phase detection? (High/Medium/Low)
-- **Information Gaps:** What information would improve this assessment?
-- **Alternative Interpretations:** Are there other ways to interpret the current state?
+After displaying output, prompt the user to save using `AskUserQuestion` with options "Yes (Recommended)" and "No".
+
+If confirmed, post a structured comment to each issue via `gh issue comment`. Each posted comment should include:
+- The action headline (`→ ACTION — reason`)
+- The workflow (for PROCEED/REWRITE)
+- Standard HTML markers on separate lines:
+  ```
+  <!-- assess:action=PROCEED -->
+  <!-- assess:phases=spec,exec,qa -->
+  <!-- assess:quality-loop=true -->
+  ```
 
 ## Notes
 
-- This command is **read-only** - it analyzes but doesn't make changes
-- It recommends but doesn't execute the next command
-- Keep the assessment concise - aim for clarity, not exhaustiveness
-- When in doubt about phase, say so - better to acknowledge uncertainty
-- Use this to orient yourself, then proceed with the appropriate workflow command
+- This command is **read-only** — analyzes but doesn't make changes
+- Batch mode should be scannable in under 5 seconds
+- Downstream tools own detail — spec owns AC breakdown, qa owns health
+- When in doubt, acknowledge uncertainty in the reason column
 
 ---
 
 ## Output Verification
 
-**Before responding, verify your output includes ALL of these:**
-
-- [ ] **Issue Summary** - Issue number, title, status, last activity, phase
-- [ ] **AC Coverage** - Each AC marked MET/IN_PROGRESS/NOT_STARTED/UNCLEAR
-- [ ] **Artifacts Found** - Planning, implementation, and QA artifacts listed
-- [ ] **Blockers & Issues** - Any blockers or staleness identified
-- [ ] **Label Review** - Current vs suggested labels based on issue content analysis
-- [ ] **Recommendation** - Specific next command to run with rationale
-- [ ] **Confidence Level** - High/Medium/Low with information gaps noted
-
-**DO NOT respond until all items are verified.**
+**Before responding, verify:**
+
+- [ ] Every issue has exactly one action in the table
+- [ ] Run column uses correct symbol for the action/state
+- [ ] Command block only contains PROCEED and REWRITE issues
+- [ ] Commands are grouped by compatible workflow
+- [ ] Separators appear between every shown section
+- [ ] Annotations omitted when not applicable (silence = healthy)
+- [ ] HTML markers present for every assessed issue
+- [ ] Batch mode: table is the primary output, no per-issue detail sections
+- [ ] Single mode: focused summary with separators between sections