fix-nightwatch-issues

Fix Nightwatch Issues

Open Nightwatch issues are real production signals: exceptions, and slow routes, jobs, commands, and scheduled tasks. Many are stale, ops problems, or third-party blips, so read the stack trace and the occurrence stats, not the headline. Walk from the newest last-seen to the oldest.

Project context. Read .agents/nightwatch.md when the repo has one. It holds the application and environment names, the deploy model, the infra paths, and the known false premises. Then follow the repo's AGENTS.md / CLAUDE.md rules for tests, cache clears, and a dirty tree.

1. Resolve the target

Use the Nightwatch MCP tools. If they are not loaded, discover them first. list_applications gives the application id and list_environments gives the production environment. list_issues (status open, sorted by last seen) is the working set. get_issue returns the stack trace, code context, occurrence stats, and execution context.

An empty application list or issue list can mean collection is off, not that production is healthy. Check the project context (or the infra config) and report "collection is off" when that is the cause.

2. Cluster by root cause

Nightwatch groups issues by message text, not by cause, so one cause fans out into many issues. For example, one root-run command that leaves a root-owned log file surfaces as a separate "Permission denied … while attempting to log: <message>" issue for every message it swallowed. Read enough issues to group them by shared cause before you fix anything. Fix each cause once, then dispose of every issue in its cluster.

Completion criterion: every open issue in scope belongs to a cluster, even a cluster of one.

3. Classify each cluster

For each cluster, open the file:line from get_issue on current main and read the commits around it. Compare last-seen with deploys (git log --oneline -- <file>): if it stopped at a deploy of a fix, it is STALE. Then write one line per issue:

Issue #NNN: [STALE | INFRA/OPS | EXTERNAL/TRANSIENT | NOISE | LEGIT] — <one-line evidence>

• Issue #131: STALE — last seen 2026-05-02, path fixed in a1b2c3d (deployed 2026-05-03); no occurrences since
• Issue #110: INFRA/OPS — root-owned daily log file; consequence of #106; fix is logging sink + entrypoint, not app code
• Issue #144: EXTERNAL/TRANSIENT — single queue receive timeout, 1 occurrence in 30d
• Issue #150: NOISE — 404 from a bot scan on /wp-login.php

Categories:

• INFRA/OPS: permissions, a missing or disabled PHP capability, the log sink, a

container user mismatch, or an env var. Fix these in container or infra config, not app code.

• EXTERNAL/TRANSIENT: a third-party timeout or 5xx, or a network blip. Judge by

count and spread. Add a retry only if it recurs and the retry is cheap.

• NOISE: bot 404s, aborted requests, and health-check probes. Filter these in

Nightwatch sampling, not in code.

• LEGIT: a cause that still reproduces against current main. One occurrence in 30

days with no users affected rarely justifies code. A steady daily count does.

Completion criterion: every issue has a line.

4. Fix each LEGIT cluster at the right layer

The symptom rarely points at the layer that needs the fix:

• App logic: fix the code, with a test.
• Environment or permissions: fix the container setup or the infra env config.
• A slow route, job, or command: add an index (check the schema first), eager-load,

chunk, or move the work to a queue.

Make the minimal change. Verify it locally where you can. For infra that cannot run locally, say so plainly. Commit one logical fix per commit, and list every Nightwatch ref the commit covers in its body (for example Nightwatch: #106, #107-#115). Use plain refs only, never `fixes #NNN`: a GitHub auto-close keyword would close the unrelated GitHub issue that has the same number.

5. Resolve in Nightwatch

For each fixed issue, add_issue_comment with the root cause and the fix sha, then update_issue to resolved. For a cluster, do this for every member and point back to the lead cause. A fix is not verified until it is deployed and last-seen goes quiet, so note "resolved pending deploy verification" where that applies.

If an issue is LEGIT but needs an operator (a secret rotation, a CI secret, an infra apply, a vendor), commit the code part, leave the issue OPEN, and comment with exactly what unblocks it. Resolve only issues whose cause is fixed. If an issue recurs after deploy, reopen it and correct its classification.

Completion criterion: every issue in scope is resolved with a comment, or stays open with a comment that names its blocker. Report the tally with one line per cluster.

6. Offer a deploy re-check

If any issue is pending deploy verification, ask once whether to re-check it in 24–48 hours. On yes, schedule a one-time run where the harness can (in Claude Code, the schedule skill's cloud routine; failing that, CronCreate with recurring: false, which fires only while this session stays open, so say so). The prompt is plain text, since a slash command for this skill cannot run from a schedule: "With the Nightwatch MCP, read last-seen for issues #<ids>; reopen and comment on any seen after <deploy date>." Otherwise, or on no, end the report with the issue ids and the re-check date.