# agdt-initiate-optimize-issue-for-ai-agent-workflow

> **General template.** Copy this file to
> `.agdt-temp/EXPECTATIONS-agdt-initiate-optimize-issue-for-ai-agent-workflow.md`
> and specialize it for your exact command and flags before executing.

## TL;DR

Starts the optimize-issue-for-ai-agent workflow, which rewrites a Jira issue to
be more actionable for an AI agent. An issue key is required. When run outside
the issue's worktree/branch, pre-flight fails and a background auto-setup creates
the worktree and opens VS Code. When run in-context, the command renders the
optimize prompt and persists the interactive preference into the workflow
context. **Note:** in-context Copilot session launch is not yet wired (a TODO in
the code), so `--skip-copilot-session` is accepted but has no effect on the
in-context path.

## Parameters & State Keys

### CLI flags

| Flag | Effect | Default |
|------|--------|---------|
| `--issue-key` | Jira issue key to optimize. Required (falls back to `jira.issue_key`). | none |
| `--user-request` / `-u` | Optional guidance on what to focus on when optimizing. | none |
| `--interactive true\|false` | Persisted into the workflow context; forwarded to auto-setup on the preflight-fail path. | `false` |
| `--model <id>` | Copilot model id (persisted to `copilot.model_id`). | project config or `gpt-4o` |
| `--skip-copilot-session` | Accepted for signature parity. No in-context session is wired yet, so this has no effect in-context. | off |

### State keys

| Key | Role |
|-----|------|
| `jira.issue_key` | Issue under optimization (required state). |
| `jira.user_request` | Optional optimization guidance. |
| `copilot.model_id` | Persisted model id. |
| `workflow.context.interactive` | Persisted interactive preference (`"true"` / `"false"`). |
| `background.task_id` | Background auto-setup task id (preflight-fail path). |
| `worktree_setup.*` | Parameters consumed by the background setup task. |

### Environment overrides

| Variable | Effect |
|----------|--------|
| `AGENTIC_DEVTOOLS_STATE_DIR` | Pins the state directory and skips bootstrap scope derivation. |
| `AGDT_DRY_RUN` / `dry_run` state | Preview mode honored by downstream action commands. |

## Decision Points / Paths

1. **Issue key resolution** — from `--issue-key` or `jira.issue_key`; missing
   exits `1`.
2. **Pre-flight** — PASS renders the optimize prompt in-context; FAIL spawns the
   background auto-setup.
3. **In-context session** — none is started (TODO). The interactive preference
   is persisted to the workflow context for future session-launch wiring.
4. **Preflight-fail background path** — the auto-setup injects a VS Code
   auto-start task using the workflow-agnostic start prompt (hand off to
   `@agdt.get-next-workflow-prompt`) and opens VS Code; the generic background
   session starter is skipped because this workflow has no prompt-filename
   mapping.

## Execution Flow

1. Parse flags; resolve `model`.
2. Resolve bootstrap scope and clear workflow tracking state (issue-context keys
   are preserved); set `copilot.model_id`.
3. Resolve the issue key from the CLI or state; exit `1` if missing.
4. Run the pre-flight check.
5. **Pre-flight FAIL** → build the nested auto-execute command and call
   `perform_auto_setup("optimize-issue-for-ai-agent", ...)`; on success print and
   return.
6. **Pre-flight PASS** → re-persist `jira.issue_key` if needed, then
   `initiate_workflow("optimize-issue-for-ai-agent", ...)` (requires
   `jira.issue_key`, optional `jira.user_request`).
7. Persist the interactive preference into the workflow context. No Copilot
   session is started (TODO).

## Observable Side Effects

- **Worktree** — created on the preflight-fail path, with VS Code settings
  injected and an auto-start task using the workflow-agnostic prompt.
- **State directory** `.agdt/workflows/{identity}/{worktree_key}/` containing
  `state.json` and the rendered
  `temp-optimize-issue-for-ai-agent-initiate-prompt.md`.
- **Workflow state** set to `optimize-issue-for-ai-agent` with the interactive
  preference recorded in its context.
- **Background task** record + logs (preflight-fail path).
- **Process / VS Code** — a new VS Code window on the preflight-fail path; no
  session is launched directly by the in-context path.

## Success Criteria

1. Missing issue key exits `1`.
2. On the in-context path the optimize prompt is rendered, the workflow state is
   `optimize-issue-for-ai-agent`, and the interactive preference is recorded.
3. On the preflight-fail path the worktree is created and VS Code is opened with
   the auto-start task injected.
4. No duplicate or unexpected Copilot session is spawned by the in-context path
   (none is wired yet).

## AI Agent Session Choreography

optimize-issue-for-ai-agent is **single-step**: the rendered prompt is a
self-contained five-step playbook the agent follows within one session.

### Session entrypoint

- **In-context path:** the optimize prompt is rendered to
  `temp-optimize-issue-for-ai-agent-initiate-prompt.md` and the interactive
  preference is persisted into the workflow context, but **the Copilot session is
  not auto-started** — in-context session launch is a code TODO (see
  `initiate_optimize_issue_for_ai_agent_workflow` in
  [`commands.py`](../../agentic_devtools/cli/workflows/commands.py)). The agent
  (or human) opens the rendered prompt to begin.
- **Preflight-fail path:** auto-setup creates the worktree and opens VS Code; the
  agent picks up the rendered prompt there.

### Step-by-step choreography (within the single session)

| Step | What the prompt asks | Commands the agent is expected to run |
|------|----------------------|---------------------------------------|
| 1. Retrieve | Fetch current issue details | `agdt-get-jira-issue` |
| 2. Analyze | Score the issue against an AI-clarity checklist (summary, description, ACs, scope, dependencies, technical context, no vague terms) | (reasoning; no command) |
| 3. Rewrite | Prepare an improved summary/description preserving original intent | (drafting; no command) |
| 4. Update | Apply the improvements | `agdt-set jira.summary "..."`, `agdt-set jira.description "..."`, then `agdt-update-jira-issue` |
| 5. Document | Comment explaining what changed and why | `agdt-add-jira-comment --jira-comment "h4. Issue Optimized for AI Agent ..."` |

The prompt is scoped to **metadata only** — it must not change the issue's intent
or implement code — and tells the agent to ask for clarification if the request
conflicts with the existing scope.

### Subagents

No workflow state-machine subagents are spawned. An auditing agent running
[`agdt.test-workflow`](../../.github/prompts/agdt.test-workflow.prompt.md) spawns
a rubber-duck subagent to review its specialized expectations document.

## Workflow Diagram

```mermaid
flowchart TD
    Start([Command invoked]) --> Parse[Parse flags and resolve model]
    Parse --> Scope[Bootstrap scope and clear tracking state]
    Scope --> Key{Issue key available}
    Key -- No --> ExitKey[Print error and exit 1]
    Key -- Yes --> Preflight{In correct worktree and branch}
    Preflight -- No --> AutoSetup[Spawn background worktree auto-setup]
    AutoSetup --> Return[Print success and return]
    Preflight -- Yes --> Initiate[Render optimize issue prompt and set workflow state]
    Initiate --> Context[Persist interactive preference in workflow context]
    Context --> NoSession[Return without starting a session]
```

---

This is a **general template**. Copy it to
`.agdt-temp/EXPECTATIONS-agdt-initiate-optimize-issue-for-ai-agent-workflow.md`
and **specialize** it for your exact command and flags before executing.
