Agent Self-Orientation Checklist Generation Prompt

This prompt is for AI coding agents that need to perform a reliable, repeatable self-check before executing any task inside a repository. The job-to-be-done is generating a runnable checklist of discovery steps, tool capability confirmations, and constraint verifications that the agent must complete to avoid common early-task failures. The ideal user is an AI engineer or platform developer wiring an agent into a CI pipeline, IDE extension, or autonomous coding harness where the cost of a misconfigured first step—wrong working directory, missing authentication, incorrect branch—is high.

Use this prompt when your agent first enters a repository or when the execution environment changes between tasks. It is not a replacement for static configuration or environment provisioning scripts; it is a dynamic, model-driven verification that the agent's runtime assumptions match reality. The prompt requires the agent to introspect its available tools, confirm filesystem access, validate environment variables, and assert that it can perform basic operations like reading a known file or running a build command. The output is a structured checklist with pass/fail states, not a narrative summary.

Do not use this prompt for agents operating in fully sandboxed, pre-configured environments where every capability is guaranteed by the harness. It is also inappropriate for one-shot, stateless completions where the agent has no persistent execution context. If the agent's task involves high-risk operations like database migrations, production deployments, or destructive file operations, the checklist must include a human approval gate before proceeding. The next step after generating the checklist is to execute it and log the results, halting the agent if any critical check fails.

This prompt template is designed to be injected into a coding agent's system instructions or used as a pre-task invocation. It forces the agent to produce a concrete, ordered checklist of discovery steps, tool capability verifications, and constraint confirmations before it attempts any file modification, code execution, or analysis. The output is not a plan for the user's task; it is a plan for the agent to orient itself. The template uses square-bracket placeholders that your application harness must populate with runtime context before sending the prompt to the model.

textCopy
You are a coding agent preparing to execute a task inside a repository. Before you begin any work, you must generate a self-orientation checklist. This checklist will be executed step-by-step to verify your environment, capabilities, and understanding of the codebase.

Generate a checklist in the following structured format. Each item must be a single, verifiable action. Do not include items you cannot execute with your available tools.

## Required Inputs
- Task Description: [TASK_DESCRIPTION]
- Working Directory: [WORKING_DIRECTORY]
- Available Tools: [AVAILABLE_TOOLS]
- Repository Structure (top-level): [REPO_STRUCTURE_SUMMARY]
- User-Provided Constraints: [USER_CONSTRAINTS]

## Output Schema
Produce a JSON object with the following structure:
{
  "agent_checklist": [
    {
      "step_id": "string (e.g., '1.1')",
      "category": "string (one of: 'environment', 'tool_check', 'codebase_discovery', 'constraint_verification', 'task_analysis')",
      "action": "string (a clear, imperative instruction to yourself)",
      "expected_outcome": "string (what success looks like for this step)",
      "tool_required": "string | null (the specific tool name from Available Tools needed, or null if none)",
      "failure_mode": "string (what could go wrong and how to detect it)",
      "blocking": "boolean (if true, the task cannot proceed if this step fails)"
    }
  ],
  "critical_path": ["step_id", "..."] (ordered list of step_ids that must succeed before any file modification),
  "abort_conditions": ["string"] (list of specific failure descriptions that should cause the agent to stop and report to the user)
}

## Checklist Generation Rules
1. **Environment First**: Always begin with steps to confirm the current working directory, environment variables, and shell state.
2. **Tool Grounding**: For every tool in [AVAILABLE_TOOLS], add a step to verify it is callable and returns a valid response. Do not assume a tool works.
3. **Task Decomposition**: Analyze [TASK_DESCRIPTION] and add discovery steps for every file, symbol, or pattern you will likely need to read or modify.
4. **Constraint Binding**: For every constraint in [USER_CONSTRAINTS], add a verification step. For example, if a constraint says "do not modify tests," add a step to identify test directories and confirm you will exclude them.
5. **Failure Modes**: For every step, explicitly state what failure looks like and how you will detect it (e.g., "tool returns a non-zero exit code," "file not found," "permission denied").
6. **Blocking Logic**: Mark a step as `blocking: true` if its failure makes the primary task impossible or unsafe to continue.
7. **Critical Path**: The `critical_path` array must contain the ordered list of `step_id`s that must succeed before you are allowed to modify any file or execute any command with side effects.

## Example Step
{
  "step_id": "1.1",
  "category": "environment",
  "action": "Run 'pwd' to confirm the current working directory matches [WORKING_DIRECTORY].",
  "expected_outcome": "The output of 'pwd' is exactly [WORKING_DIRECTORY].",
  "tool_required": "execute_command",
  "failure_mode": "'pwd' returns a different path, indicating the agent shell is not in the expected directory.",
  "blocking": true
}

Generate the full checklist now based on the provided inputs.

To adapt this template, your application harness must first gather the five required inputs: the user's task description, the absolute working directory path, a list of tool names and signatures available to the agent, a summary of the repository's top-level structure, and any explicit user constraints. Populate these into the square-bracket placeholders before sending the prompt. The output JSON must be parsed and validated by your harness. Each step's tool_required field should be cross-referenced against your actual tool registry to prevent the agent from hallucinating unavailable tools. If the agent's checklist includes a tool not in [AVAILABLE_TOOLS], the harness should reject the checklist and re-prompt with a corrected tool list. For high-stakes environments, require human approval of the critical_path and abort_conditions before the agent begins executing the checklist.

This prompt is designed to be the first tool call an agent makes when entering a new repository or resuming a session after a context reset. The harness should invoke it before any file modification, build execution, or dependency installation. The generated checklist is not just a display artifact—it must be parsed into a structured task list that the agent's planner can consume. Each checklist item should include a tool requirement (e.g., run_command, read_file, search_code) and a success criterion that the harness can later verify. The harness must store the checklist in the agent's working memory and prevent execution of any non-discovery task until the checklist is marked complete or explicitly overridden by a human operator.

Wire the prompt into a pre-flight hook that fires on session start or when the agent's working directory changes. The harness should inject the current working directory, available tool list, and any user-provided constraints into the [REPOSITORY_PATH], [AVAILABLE_TOOLS], and [CONSTRAINTS] placeholders respectively. After the model returns the checklist, validate the output against a strict schema: each item must have an id, action, tool, target, and success_condition field. Reject any checklist item that references a tool not in the provided tool list. If validation fails, retry once with the validation errors injected into the [PREVIOUS_ERRORS] field of a retry prompt. Log the raw checklist and validation results for observability. For high-risk repositories (production infrastructure, monorepos with deployment pipelines), require a human to approve the checklist before the agent proceeds to execution.

Model choice matters here. Use a model with strong instruction-following and structured output capabilities (GPT-4o, Claude 3.5 Sonnet, or equivalent). Avoid smaller models that may hallucinate tool names or skip critical discovery steps like authentication checks. The harness should enforce a token budget for the checklist output—if the generated checklist exceeds 50 items, truncate and flag for human review, as an overly granular checklist often indicates the agent failed to prioritize. After checklist execution, the harness must compare actual results against each item's success_condition. Items that fail should be re-queued with context from the failure. If more than 20% of items fail, abort the orientation and escalate to a human operator with the failure log. Never allow the agent to proceed to file modification or build execution with unresolved checklist failures.