PromptWorks/lights-out/references/prompts.md

# Prompt templates

These templates are for Lights Out runs powered by the vendored `nightshift` engine. The prompt
passed via `-Prompt` is what the coding agent sees on every iteration.

It is the single biggest lever on overnight quality. Fill the placeholders; do not send a bare
one-liner.

## Worker prompt (new run)

```text
Objective: <one concrete outcome>.

Work in this repository. Treat this as a long-running unattended task — nobody is watching, so
never wait for confirmation and never leave the tree in a broken state between commits.

Before changing anything, read the relevant code, docs, and recent commits to understand current
behavior. Preserve existing user work. Do not refactor anything outside <scope>.

Non-goals: <what must not change — files, APIs, behavior, dependencies>.

After each meaningful slice, run: <verification command>. If it fails, fix it before moving on.

If you hit a genuine blocker, stop and write the blocker plus the evidence into your notes. Never
fabricate success, never disable or skip a test to make something pass, and never commit a change
you have not verified.

Stop only when: <observable completion condition>.
```

### Writing the scope and non-goals

Vague scope is the main cause of a morning spent reading an unwanted refactor. Be concrete:

- Good scope: "only files under `src/utils/`"
- Good non-goal: "do not change any public export signature; do not add dependencies"
- Bad: "don't break anything"

### Writing the stop condition

It must be checkable by looking at the repo, not by asking an opinion.

| Bad | Good |
|---|---|
| the code is cleaner | `npm test` exits 0 and no file outside `src/utils/` is modified |
| tests look fine | the full suite passes with zero skipped tests |
| done with the refactor | `npm run typecheck` and `npm test` both exit 0, and `git diff --stat` shows no change to `package.json` |

## Steering prompt (continue after a partial success)

```text
Continue from the current repository state. A previous run partially succeeded: <specific evidence
— commits, files, what now works>.

Do not redo that completed work and do not revisit <areas already settled>.

Focus only on: <single bounded correction>.

The specific problem to fix is: <observed issue, with file and line where known>.

Verify with: <commands or checks>.

Stop only when: <observable condition for this correction alone>.
```

## Findings prompt (user rejected the result)

One finding per run. Bundling corrections is how scope drift restarts.

```text
Continue from the current repository state on this branch.

A review found this blocking issue: <finding, in the user's own words, with severity and file/line
scope preserved>.

Keep all other completed work intact — do not revert or rewrite anything unrelated to this finding.

Fix only that issue. Verify with: <commands>.

Stop only when: <the finding is demonstrably no longer true>.
```

## Research-first prompt (exploratory work)

Use when the objective is not yet well understood. Forces investigation before edits.

```text
Objective: <outcome>.

First deliverable, before any code change: investigate <question> and write your findings into your
notes — what you examined, what you concluded, and which approach you chose with the reason.

Only after recording that, implement the chosen approach in <scope>.

Verify with: <command>. Non-goals: <...>.

Stop only when: <observable condition>.
```

## Anti-patterns

- **No verification command.** The agent grades its own homework and always passes.
- **Unbounded scope.** "Improve the codebase" produces a diff nobody wants to review.
- **Opinion stop conditions.** The run either never stops or stops arbitrarily.
- **Multiple objectives in one prompt.** Split them into separate runs, or use `-Worktree`.
- **Omitting non-goals.** Agents reformat, upgrade dependencies, and rename things when unconstrained.