Prompting Guide

Prompting Guide¶

Effective prompts for working with AI assistants in ctx-enabled projects.

This guide documents prompts that reliably produce good results.

Session Start¶

"Do you remember?"¶

Triggers the AI to read AGENT_PLAYBOOK, CONSTITUTION, sessions/, and other context files before responding.

Use this during the start of every important session.

Do you remember what we were working on?

This question implies prior context exists. So, the AI checks files rather than admitting ignorance.

"What's the current state?"¶

Prompts reading of TASKS.md, recent sessions, and status overview.

Use this when resuming work after a break.

Variants:

• "Where did we leave off?"
• "What's in progress?"
• "Show me the open tasks"

During Work¶

"Why doesn't X work?"¶

This triggers root cause analysis rather than surface-level fixes.

Use this when something fails unexpectedly.

Framing as "why" encourages investigation before action. The AI will trace through code, check configurations, and identify the actual cause.

"Is this consistent with our decisions?"¶

This prompts checking DECISIONS.md before implementing.

Use this before making architectural choices.

Variants:

• "Check if we've decided on this before"
• "Does this align with our conventions?"

"What would break if we..."¶

This triggers defensive thinking and impact analysis.

Use this before making significant changes.

What would break if we change the Settings struct?

"Before you start, read X"¶

This ensures specific context is loaded before work begins.

Use this when you know the relevant context exists in a specific file.

Before you start, read .context/sessions/2026-01-20-auth-discussion.md

Reflection and Persistence¶

"What did we learn?"¶

This prompts reflection on the session and often triggers adding learnings to LEARNINGS.md.

Use this after completing a task or debugging session.

This is an explicit reflection prompt. The AI will summarize insights and often offer to persist them.

"Add this as a learning/decision"¶

This is an explicit persistence request.

Use this when you have discovered something worth remembering.

Add this as a learning: "JSON marshal escapes angle brackets by default"

# or simply.
Add this as a learning.
# and let the AI autonomously infer and summarize.

"Save context before we end"¶

This triggers context persistence before the session closes.

Use it at the end of the session or before switching topics.

Variants:

• "Let's persist what we did"
• "Update the context files"
• /ctx-save (slash command in Claude Code)

Exploration and Research¶

"Explore the codebase for X"¶

This triggers thorough codebase search rather than guessing.

Use this when you need to understand how something works.

This works because "Explore" signals that investigation is needed, not immediate action.

"How does X work in this codebase?"¶

This prompts reading actual code rather than explaining general concepts.

Use this to understand the existing implementation.

How does session saving work in this codebase?

"Find all places where X"¶

This triggers a comprehensive search across the codebase.

Use this before refactoring or understanding the impact.

Meta and Process¶

"What should we document from this?"¶

This prompts identifying learnings, decisions, and conventions worth persisting.

Use this after complex discussions or implementations.

"Is this the right approach?"¶

This invites the AI to challenge the current direction.

Use this when you want a sanity check.

This works because it allows AI to disagree. AIs often default to agreeing; this prompt signals you want an honest assessment.

"What am I missing?"¶

This prompts thinking about edge cases, overlooked requirements, or unconsidered approaches.

Use this before finalizing a design or implementation.

Anti-Patterns¶

Based on our ctx development experience (i.e., "sipping our own champagne") so far, here are some prompts that tend to produce poor results:

Quick Reference¶

Writing Tasks as Prompts¶

Tasks in TASKS.md are indirect prompts to the AI. How you write them shapes how the AI approaches the work.

State the Deliverable, Not Just Steps¶

Bad task (implementation-focused):

- [ ] T1.1.0: Parser system
  - [ ] Define data structures
  - [ ] Implement line parser
  - [ ] Implement session grouper

The AI may complete all subtasks but miss the actual goal. What does "Parser system" deliver to the user?

Good task (deliverable-focused):

- [ ] T1.1.0: Parser CLI command
  **Deliverable**: `ctx recall list` command that shows parsed sessions
  - [ ] Define data structures
  - [ ] Implement line parser
  - [ ] Implement session grouper

Now the AI knows the subtasks serve a specific user-facing deliverable.

Use Acceptance Criteria¶

For complex tasks, add explicit "done when" criteria:

- [ ] T2.0: Authentication system
  **Done when**:
  - [ ] User can register with email
  - [ ] User can log in and get a token
  - [ ] Protected routes reject unauthenticated requests

This prevents premature "task complete" when only the implementation details are done but the feature doesn't actually work.

Subtasks ≠ Parent Task¶

Completing all subtasks does not mean the parent task is complete.

The parent task describes what the user gets. Subtasks describe how to build it.

Always re-read the parent task description before marking it complete. Verify the stated deliverable exists and works.

Contributing¶

Found a prompt that works well? Open an issue or PR with:

1. The prompt text
2. What behavior it triggers
3. When to use it
4. Why it works (optional but helpful)