# Tasks, prompts, and context

>  © 2026 Quadropic Pvt Ltd. Proprietary and confidential. [Use restrictions](NOTICE.md).

## Choose the action before writing the prompt

The action is a runtime instruction, not just a label.

| Action | Use it when | What the harness asks the agent to do | Avoid it when |
|---|---|---|---|
| **Submit** | You want an outcome completed end to end | Inspect, edit when needed, validate, and report | You only want analysis |
| **Architect** | You need a reviewable implementation plan | Inspect the code, write a durable plan, and avoid implementation edits | The task is already small and obvious |
| **Ask** | You want an explanation, comparison, or orientation | Answer with repository context and avoid edits unless clearly requested | You expect a broad implementation |
| **Debug** | Symptoms exist but the cause is unclear | Reproduce or inspect first, then make a focused fix | You already know the exact mechanical edit |

The secondary action button cycles through Architect, Ask, and Debug. Use `Shift+Tab` to cycle and `⌘⇧Enter` / `Ctrl+Shift+Enter` to run the active secondary action. Plain `Enter` submits; `Shift+Enter` creates a new line.

### Action routing and presets

With Standard selected:

- Ask routes to the fast Light assignment.
- Architect and Debug route to Hunter.
- Submit stays on Standard.

If you explicitly select Hunter, Design, Browser, or a custom preset, that selection is retained for the action. This lets you deliberately use a specialized model for an Ask or Debug request.

## Write outcome-first prompts

A useful task brief contains five things:

1. **Outcome** — observable behavior, not “improve this.”
2. **Scope** — relevant feature, directory, or files.
3. **Evidence** — errors, screenshots, logs, reproduction, or a comparison.
4. **Constraints** — compatibility, dependencies, APIs, files, or behaviors that must stay unchanged.
5. **Validation** — a command, test, or manual scenario that proves completion.

Example:

```text
Fix the duplicate notification shown after reconnect.

Reproduction:
1. Open the companion.
2. Disconnect Wi-Fi for 10 seconds.
3. Reconnect and complete a task.
4. Two completion notifications appear.

Scope: mobile notification sync and reconnect handling.
Constraints: preserve live-activity behavior and do not add a dependency.
Done when: one notification appears after normal completion and after reconnect,
and the relevant unit tests pass.
```

### Say what autonomy you want

Good phrases:

```text
Handle this end to end and make reasonable implementation decisions.
```

```text
Diagnose only. Give me the cause, evidence, and smallest safe fix; do not edit.
```

```text
Implement the fix, but stop and ask before changing the persisted data format.
```

```text
Use the narrowest relevant tests. Do not run the full suite unless the focused
checks expose a cross-cutting risk.
```

Avoid narrating every implementation step before inspection. “Use a new context provider, add three hooks, and rewrite the reducer” may force a worse design than the codebase suggests. Make architecture a constraint only when it truly is one.

## Add focused context

### `@` mentions

Type `@` in the composer to search:

- workspace files;
- directories;
- installed skills;
- installed MCP tools.

Use arrow keys to move, `Enter` or `Tab` to select, and `Esc` to close.

Mentions are best when:

- a filename is ambiguous;
- only one subsystem is in scope;
- a specific Skill should govern the workflow;
- you want a particular MCP tool available without asking the agent to discover it.

Mention the smallest useful boundary. `@src/features/auth/session.ts` is higher signal than mentioning the entire repository.

### Images

Use the image button, paste an image, or press `⌘⇧I` / `Ctrl+Shift+I`.

Images are valuable for:

- UI bugs and visual regressions;
- target designs;
- diagrams;
- terminal errors that cannot be copied;
- comparing “current” and “expected.”

Label multiple images in the prompt (“first image is current; second is expected”). A model assigned to the selected preset must support vision to use them reliably.

### Logs and errors

Paste the smallest complete failure:

- include the first causal error, not hundreds of follow-on lines;
- include the command that produced it;
- preserve filenames, line numbers, status codes, and timestamps that matter;
- redact secrets, tokens, personal data, and private URLs.

If the output is large, put it in a workspace file and mention the file.

## Use the composer efficiently

- `⌘K` / `Ctrl+K`: focus the composer.
- `Enter`: Submit.
- `Shift+Enter`: newline.
- `Shift+Tab`: cycle Architect, Ask, and Debug.
- `⌘⇧Enter` / `Ctrl+Shift+Enter`: run the selected secondary action.
- `⌘⇧M` / `Ctrl+Shift+M`: open model preset selection.
- `⌘⇧I` / `Ctrl+Shift+I`: add an image.
- `⌘⇧E` / `Ctrl+Shift+E`: queue a Virtual Edit for the next new thread.
- `⌘⌥C` / `Ctrl+Alt+C`: compress the active thread context.
- `⌘Esc` / `Ctrl+Esc`: stop the active agent.

The context ring around the send button shows estimated usage of the current model’s context window. Hover it for token and source details.

## Steer a running agent

You can send another message while a run is active. Treat steering as a delta:

```text
New evidence: the failure only occurs when featureFlagX is false.
Prioritize that branch; keep the public API unchanged.
```

```text
Stop exploring the serializer. The failing response is already malformed before
serialization; inspect the request builder next.
```

Useful steering:

- corrects a false assumption;
- adds a reproduction detail;
- changes a priority;
- narrows or expands scope explicitly;
- answers a question the agent could not resolve.

Counterproductive steering:

- repeats the original prompt;
- sends several speculative fixes;
- changes the goal without saying the previous goal is superseded;
- asks for status every few seconds.

If the course is fundamentally wrong, stop the run and start a fresh thread with a corrected brief. Use `⌘Esc` / `Ctrl+Esc` so an ordinary Escape key cannot accidentally terminate work.

## Handle approvals and questions

An agent can pause for either a tool approval or a structured question.

Before approving a tool:

1. Check the tool name.
2. Read every argument, especially command, path, URL, and target.
3. Confirm it belongs to the active workspace and task.
4. Choose the narrowest duration.

**Allow Once** is appropriate for a one-off shell command or write. **This Turn** is useful when a trusted tool will repeat with similar safe arguments. A global **Allow** in Settings applies to later tasks too, so use it only for tools whose full scope you understand.

When the agent asks a question, answer the decision it needs and explain the governing constraint. “Option B because old clients must continue to deserialize this field” is much more useful than “B.”

## Keep context healthy

Long threads accumulate messages, tool results, and decisions. More context is not always better.

Start a new thread when:

- the objective changes;
- the old task is complete;
- you are switching to an unrelated subsystem;
- the agent is anchored on outdated assumptions;
- you need a clean model or workspace boundary.

Compress the current context when:

- the objective is unchanged;
- earlier exploration is still relevant but too verbose;
- the context ring is approaching 75–90%;
- the provider reports a request that is too large.

To compress:

- press `⌘⌥C` / `Ctrl+Alt+C`; or
- with an empty composer, hold or right-click the send control when compression is available.

Compression writes a summary and retains recent context. Afterward, send a short checkpoint:

```text
Continue toward the same acceptance criteria. The authoritative decisions are:
1. preserve the v1 payload;
2. no new dependency;
3. validate with npm test -- session.
```

Do not wait until the context is completely full. Compression has better material to summarize when the thread is still coherent.

## Review the response as evidence

A useful completion should tell you:

- what changed;
- where it changed;
- what was validated;
- what was not validated;
- any remaining risk or decision.

Open File Diff instead of relying only on the prose. If the run says a test passed, the output should correspond to an actual executed command. For high-risk changes, rerun the important check yourself in the integrated Terminal.