Skip to content

leek/agent-skills / skills/fix-nightwatch-issues

fix-nightwatch-issues

Verified

Triage open Laravel Nightwatch production issues by root cause, fix the legit ones, and resolve them with evidence.

FileKindSize
SKILL.mdskill md6.2 KB
agents/openai.yamlconfig210 B
references/nightwatch-mcp.mdmarkdown1.1 KB
---
name: fix-nightwatch-issues
description: Triage open Laravel Nightwatch production issues by root cause, fix the legit ones, and resolve them with evidence.
disable-model-invocation: true
argument-hint: "Optional issue numbers or a type filter (exception, route, job, command, scheduled_task); defaults to all open issues"
compatibility: "Requires the Laravel Nightwatch MCP server"
---

# 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

Read [`references/nightwatch-mcp.md`](references/nightwatch-mcp.md) before your first
Nightwatch call. It covers finding the application and the production environment, the
issue tools, an issue that will not load, and the resolve calls. The working set is the
`open` issues of the production environment, ordered by last seen.

An issue whose detail will not load is a problem with that one issue's payload, not with
the environment. Work from its list summary and the other issues in its cluster, and
name it as unread in the report.

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 the issue detail 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, proved per the `tdd` skill's
  [What needs a test](../tdd/SKILL.md#what-needs-a-test-and-what-proves-the-rest).
- 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

First run `list_issues` with status `open` again: the user often resolves or ignores
issues in the Nightwatch UI while the run works. Skip any issue no longer in that list
and name it in the tally; do not comment on it or set its status again. For each fixed issue still open, comment with the root cause and the fix sha,
then set it 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, starting ✅ resolved or ⚠️ open with a blocker.

## 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.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall