Category Taxonomy

Six suggestion categories with tier-based slot allocation. No floating-point arithmetic — tiers and integer slot counts only.

Categories

⚡ Direct Follow-up (Default Tier: STRONG)

The logical next action that continues the user's current work trajectory.

Slot rule: 1 guaranteed slot always.

Examples:

• User just implemented JWT auth → "Implement token refresh with sliding expiry window"
• User fixed a database query → "Add an index on the column you just filtered by"
• User wrote a React component → "Write unit tests for the edge cases in your conditional rendering"

Anti-examples (violate anti-patterns):

• "Would you like to know more about JWT?" (restating the obvious)
• "What are the pros and cons of your approach?" (generic filler)

🔧 Actionable Task (Default Tier: STRONG)

A concrete thing the user can do right now, grounded in their project state.

Slot rule: 1 guaranteed slot always.

Examples:

• "Add error handling to the 3 unhandled promise rejections in your API routes"
• "Create a migration script for the schema change you just discussed"
• "Set up a pre-commit hook for the linting rules you configured"

Anti-examples:

• "Consider improving your code quality" (too broad)
• "Maybe add some tests" (vague, non-specific)

🔍 Deep Dive (Default Tier: MODERATE)

Go deeper into a specific technical aspect the user is working with.

Slot rule: 1 slot when display-count ≥ 3.

Examples:

• "Deep-dive: Compare HMAC vs RSA for your token signing — security vs performance tradeoffs for your scale"
• "Explore: Connection pooling strategies for your PostgreSQL setup — you're creating a new connection per request"
• "Research: Rate limiting algorithms for your API — token bucket vs sliding window for your use case"

Anti-examples:

• "Learn about databases" (too broad)
• "What is PostgreSQL?" (trivially lookupable)

📋 Memory Recall (Default Tier: MODERATE)

Surfaces unfinished tasks from BACKLOG.md that are relevant to the current context.

Slot rule: 1 slot when a relevant backlog item exists.

Tag format: Always prefix with "Resume:", "From backlog:", or "You mentioned:".

Examples:

• "Resume: Complete the RBAC role hierarchy — started 3 days ago, still on your backlog"
• "From backlog: The API rate limiter you planned last session — relevant now that you're working on the API layer"
• "You mentioned: Wanting to add WebSocket support — your new real-time feature would benefit"

Anti-examples:

• Surfacing a backlog item completely unrelated to current context
• Surfacing an item the user explicitly dismissed

💡 Lateral / Out-of-the-Box (Default Tier: MODERATE)

Creative, non-obvious but relevant suggestion the user probably hasn't considered.

Slot rule: 1 slot when display-count ≥ 3.

Examples:

• "Consider: What happens to active sessions during your zero-downtime deploy? Token migration strategy."
• "Lateral: Your auth service could double as an audit log — you're already tracking user actions"
• "What if: Use your existing caching layer for rate limiting instead of adding Redis"

Anti-examples:

• Completely random ideas with no connection to context
• Ideas that require entirely different technology stacks

✅ Quick Win (Default Tier: MODERATE)

Small action completable in under 5 minutes that improves the project.

Slot rule: Fills remaining slots after all other categories are allocated.

Examples:

• "Quick win: Add your 3 unprotected Express routes to the auth middleware — 5-minute fix"
• "Quick win: Add a .env.example file so new contributors know which env vars to set"
• "Quick win: Pin your dependency versions in package.json — prevents surprise breaks"

Anti-examples:

• Tasks that actually take hours ("Quick win: refactor the database layer")
• Tasks with no clear completion criteria

Slot Allocation Algorithm

Given display-count = N:

1. Assign 1 slot to each STRONG category (Direct Follow-up + Actionable Task = 2 slots minimum)
2. If N ≥ 3 and include-lateral is true: assign 1 slot to Lateral
3. If N ≥ 3: assign 1 slot to Deep Dive
4. If relevant backlog exists and include-backlog is true: assign 1 slot to Memory Recall
5. Fill remaining slots with Quick Win or other MODERATE categories based on user's Category Preferences tiers
6. If a category is in excluded-categories, skip it entirely and redistribute its slot

When display-count is 1-2: only STRONG categories (or the user's highest-tier categories if customized).

Tier Promotion/Demotion

Tiers adjust through the self-improvement protocol:

• 3+ selections of a MODERATE category in last 10 history entries → promote to STRONG
• 0 selections of a STRONG category in last 15 entries where it was presented → demote to MODERATE
• User explicitly excludes a category → move to EXCLUDED (not a tier — a hard block)
• Tiers are: STRONG > MODERATE > WEAK. EXCLUDED is separate.

See SELF-IMPROVE.md for the full promotion/demotion protocol.