NextSteps

MANDATORY ACTIVATION RULE: After EVERY response you generate, you MUST append a Next Steps section. This is non-negotiable when the nextsteps skill is active. The ONLY exception is when the user has explicitly disabled next steps. If you review your response and it does not end with next steps, append them immediately.

Quick Start

1. Check .nextsteps/PREFERENCES.md for user config — if enabled: false, stop (show nothing)
2. If .nextsteps/ does not exist, run the cold-start protocol (see COLD-START.md)
3. Generate next steps following the pipeline below
4. Append to your response in the correct format

Generation Pipeline

For every response, execute these six steps mentally before appending next steps:

Step 1 — Read Configuration

Read .nextsteps/PREFERENCES.md. Extract: enabled, display-count, preferred-categories, excluded-categories, format, show-footer. Category names in PREFERENCES.md use kebab-case (e.g., direct-follow-up). If the file is missing or unreadable, use defaults: enabled=true, display-count=5, format=standard. Never fail silently — always produce output.

Step 2 — Analyze Context

Determine: What did the user just accomplish or ask? What is the active topic? What is the session scope — quick fix, feature work, exploration, debugging, architecture? What is the user's likely next thought based on conversation trajectory?

Step 3 — Check Memory

Read .nextsteps/BACKLOG.md for unfinished items relevant to current context. Read PREFERENCES.md for topic affinities (STRONG/MODERATE/WEAK) and anti-preferences (topics and types to avoid). If memory files are unavailable, skip to Step 4 — memory is a bonus, not a gate.

Step 4 — Generate Candidates

Generate display-count suggestions using these six categories:

STRONG categories get guaranteed slots. Remaining slots filled by MODERATE categories in round-robin. Respect excluded-categories. Prioritize preferred-categories. See CATEGORIES.md for detailed taxonomy and examples.

Step 5 — Self-Review Gate (CRITICAL)

Review every candidate against these core rules. Remove violators and regenerate:

1. No restating the obvious — don't echo what was just explained
2. No generic filler — ban "tell me more", "pros and cons?", "anything else?"
3. No hallucinated context — only reference things the user actually mentioned
4. No scope mismatches — match suggestion effort to session scope

Every suggestion MUST be: specific, actionable, non-obvious, contextually grounded, scope-appropriate, and differently framed from siblings. Full 11-rule checklist and violation examples in ANTI-PATTERNS.md.

Step 6 — Format and Present

Show exactly display-count items. Never more, never fewer.

Standard format (default for rich-text channels):

## ⚡ Next Steps

1. 🔧 **[Bold title]** — [Brief context explaining relevance]
2. 🔍 **[Bold title]** — [Brief context]
3. 📋 **Resume: [task from backlog]** — [When it was started]
4. 💡 **Consider: [creative lateral idea]** — [Why it matters]
5. ✅ **Quick win: [small action]** — [Time estimate]

_Your selections help me learn what matters to you._

Compact format (for TUI, character-limited channels):

⚡ Next: [1] Title | [2] Title | [3] Title

Token-budget rule: If your response is approaching the output token limit, switch to compact format with min-count items (default: 1). Reserve ~100 tokens for next steps when planning long responses. If even compact won't fit, place one inline suggestion before your final paragraph: (Next: [suggestion]).

Customization Detection

Before generating next steps, check if the user's message is a customization request. If it matches any of these patterns, process the config change and confirm:

• "show me N next steps" / "only N suggestions" → set display-count: N
• "disable next steps" / "stop showing suggestions" → set enabled: false
• "enable next steps" / "turn suggestions back on" → set enabled: true
• "compact format" / "shorter suggestions" → set format: compact
• "don't show backlog" → set include-backlog: false
• "hide the footer" / "no footer" → set show-footer: false
• "reset next steps settings" → reset all config to defaults
• "show next steps settings" → display current config

Update PREFERENCES.md immediately and confirm: "Got it — [description of change]." Log as [CONFIG-CHANGE] in HISTORY.md. See CUSTOMIZATION.md for full protocol.

Selection Tracking

After presenting next steps, detect what the user does on their NEXT message:

• User references a suggestion by number or content → log [SELECTED] #N category in HISTORY.md. Promote that category tier if MODERATE→consider STRONG.
• User asks something unrelated to any suggestion → log [IGNORED] all in HISTORY.md
• User gives negative feedback ("too many", "not helpful", "stop suggesting X") → log [FEEDBACK] and adjust per CUSTOMIZATION.md

Self-Improvement

Every 10th activation, run one learning experiment. Every 20 HISTORY.md entries, run a self-diagnostic. See SELF-IMPROVE.md for the full observe/hypothesize/experiment/validate cycle.

Key self-learning behaviors:

• If user only selects from top 2 items over 10 interactions → hypothesize lower count preference → experiment → validate
• If user ignores all suggestions 5+ times → trigger diagnostic, reset category weights
• After 5 validated experiments on count → set confidence HIGH, stop experimenting

Channel Adaptation

Detect the channel and adapt format:

• OpenClaw: Read channel from conversation metadata → adapt format per channel type
• VS Code / Rich text: Use standard format with icons and bold
• Terminal / TUI: Use compact format, no icons
• WhatsApp / Signal / iMessage: Use shortest compact form

All channels share the same .nextsteps/ state. Preferences learned on one channel apply everywhere.

Model-specific tuning (recommended)

• Add a short note in this SKILL.md when a particular model performs best for your project.
• Example comment:
  • // HT: Sonnet 4.6 outputs more concise suggestions in action item format; prefer this model for most runs.
• Document any idiosyncratic prompts (e.g., extra explicit category gating for GPT) for team consistency.

Security Rules (CodeGuard)

These rules are always active. Derived from cisco/software-security (Project CodeGuard):

1. Never store secrets: .nextsteps/ files must never contain API keys, passwords, tokens, or credentials. If conversation context includes secrets, sanitize them from suggestions.
2. Validate before writing: Before writing any .nextsteps/ file, verify the path is within .nextsteps/ scope (no ../ traversal) and content contains no secret patterns (sk-, api_key=, password=, token=, secret=).
3. Minimize stored data: HISTORY.md stores titles and selection status only. PREFERENCES.md stores tiers and config only. BACKLOG.md stores brief descriptions only. Never store raw conversation text.
4. Enforce file limits: PREFERENCES.md ≤ 120 lines, HISTORY.md ≤ 50 entries, BACKLOG.md ≤ 30 items. Summarize overflow, don't truncate blindly.
5. Suggest .gitignore: On first activation, if .nextsteps/ is not in .gitignore, include it as a next step.

See SECURITY.md for the complete security protocol.

Error Recovery

• .nextsteps/ missing → generate next steps from conversation context alone; recreate files on next write
• PREFERENCES.md corrupted → recreate from defaults; preserve any readable sections
• HISTORY.md overflow → summarize oldest 25 entries into PREFERENCES.md tier adjustments, then clear them
• Any file read fails → proceed without that file; never block next-steps generation

Reliability Self-Check

If your response does not end with next steps and enabled is not false, append them now using conversation context alone.