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.

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 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: " 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.
  • 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 #; reopen and comment on any seen after ." 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