Focus Scan

Purpose

Align session focus with the highest priority pending issue. Enforces that all work is tracked as issues and respects confidence-based batch limits.

Context Optimization

Read

index.md

1. Read .agent/issues/index.md (compact summary)
2. Identify target priority level from index
3. Load only that priority file for full details

CLI Commands

Works with or without

aoc

File-Based Priority Scan (Default)

1. Read .agent/issues/index.md (compact summary)
2. Identify target priority level from index
3. Load only that priority file for full details
4. Filter for status: todo or open
5. Select first actionable issue (respecting depends_on)

Focus Update (File-Based)

1. Read current

   .agent/focus.md

2. Update "Doing now" section with selected issue
3. Update "Next" section with immediate step

CLI Integration (when aoc is available)

When

aoc

.agent/tools.json

aoc issues list --status todo,open --priority critical

aoc issues list --status todo,open --priority high

aoc issues list --status blocked

aoc issues show <ID>

aoc issues summary

Confidence-Based Batch Limits

Enforcement:

• Read confidence from constitution or current task
• If LOW confidence, select EXACTLY 1 issue — no batching
• Present batch to user for confirmation if confidence is not HIGH

Issue-First Enforcement

Before starting any work:

1. Check for existing issue: Is there an issue for the requested work?

   • Yes → proceed to priority scan
   • No → prompt to create issue first

2. If user requests work without an issue:

   ⚠️ No issue found for this work.
   
   All work should be tracked for auditability.
   
   Create an issue first?
   [Y]es, create and start / [N]o, work without tracking
   
   Suggested: {TYPE}-{next}@{hash} — "{inferred title}"
   

3. Even simple chores need issues:

   • "Fix typo" →

     CHORE

     issue
   • "Update dependency" →

     CHORE

     issue
   • "Add comment" →

     DOCS

     issue
   • "Quick refactor" →

     REFAC

     issue (needs permission anyway)

Procedure

1. Check confidence level (from constitution or task):

   • Determine batch size limit
   • Note if LOW confidence (special handling)

2. Scan priority files in order (stop when actionable issue found):

   • .agent/issues/critical.md

     (scan first — highest priority)

   • .agent/issues/high.md

   • .agent/issues/medium.md

   • .agent/issues/low.md

     (only if nothing higher)
   • SKIP

     .agent/issues/backlog.md

     — backlog items need triage first

3. Identify the highest priority issue where:

   • Status is

     todo

     or

     in_progress

   • All

     depends_on

     dependencies are

     done

     (or list is empty)
   • Issue is not marked as

     blocked

     ,

     cancelled

     , or

     dropped

4. Apply batch limit based on confidence:

   For LOW confidence:

   🎯 LOW CONFIDENCE MODE — Single Issue Focus
   
   Selected: {ISSUE-ID} — {title}
   
   Batch size: 1 (hard limit for low confidence)
   
   This issue will receive:
   - Mandatory interview before planning
   - Extensive implementation details
   - Hard stop after implementation for human review
   - ≥90% test coverage requirement
   
   Proceed with this issue? [Y]es / [N]o, select different
   

   For NORMAL confidence:

   📋 Selected {N} issues for this iteration (max 3):
   
   1. {ISSUE-ID-1} — {title}
   2. {ISSUE-ID-2} — {title}
   
   Proceed? [Y]es / [M]odify selection / [S]ingle issue only
   

   For HIGH confidence:

   • Proceed with selection (up to 5), report only

5. Action based on findings:

   If an actionable issue is found:

   • Read

     .agent/focus.md

   • Update

     Doing now

     to reflect this issue (include issue ID)
   • Update

     Next

     with the immediate practical step
   • Example:

     ## Doing now
     - Working on FEAT-0012@a3f2c1: Add user authentication
     
     ## Next
     - Review existing auth patterns in codebase
     - Create implementation plan
     

   If all issues are blocked:

   • Identify the specific blockers
   • Update focus to indicate blockers need resolution
   • Suggest resolving dependencies or creating new issues

   If no prioritized issues exist but backlog has items:

   • Prompt user:

     📋 No prioritized issues, but {N} items in backlog.
     
     1. Triage backlog (/agent-task triage)
     2. Create new issue (/agent-task)
     3. Run discovery (/agent-baseline, /agent-review)
     

   If no issues exist at all:

   • Update focus to indicate planning/discovery needed
   • Prompt user:

     📋 No issues anywhere. What would you like to do?
     
     1. Create new issues (/agent-task)
     2. Run discovery to find work (/agent-baseline, /agent-review)
     3. Describe what you want to work on (I'll create an issue)