narrator/knowledge/community-practices.json

{
  "_provenance": {
    "note": "Custom, NON-Anthropic 'Generally recommended' practices — the well-known craft of working with a coding agent (read the error, change one variable at a time, scope your diffs, write the check first, pin your versions). These ride ALONGSIDE the cited Anthropic practices in signals.json (which stays untouched). Edit this file directly — no code change needed — to add, retune, or remove a practice; each is attached to a DETERMINISTIC signal `kind` the engine already fires, never invented on its own. Attribution is 'Generally recommended' (NOT Anthropic); `source` is an optional public URL or null.",
    "updated": "2026-06-06"
  },
  "practices": [
    {
      "id": "read-the-error",
      "kind": "loop",
      "attribution": "Generally recommended",
      "practice": "Read the full error before retrying",
      "fix": "The error message usually names the fix — a missing argument, a wrong path, an unbalanced quote. Read it in full before re-running; a blind retry just repeats the same failure.",
      "source": null
    },
    {
      "id": "one-variable-at-a-time",
      "kind": "near_repeat",
      "attribution": "Generally recommended",
      "practice": "Change one variable at a time",
      "fix": "When iterating on a command, change a single thing per attempt. If you change several at once and it works (or doesn't), you can't tell which change moved the needle.",
      "source": null
    },
    {
      "id": "scope-diffs-and-searches",
      "kind": "read_burst",
      "attribution": "Generally recommended",
      "practice": "Keep diffs and searches scoped",
      "fix": "Narrow the search and edit surface to what the task actually needs. Smaller, reviewable steps are easier to verify and to undo than one broad sweep across many files.",
      "source": null
    },
    {
      "id": "read-once-keep-context",
      "kind": "reread",
      "attribution": "Generally recommended",
      "practice": "Read a stable file once, keep it in context",
      "fix": "If a file isn't changing, re-opening it pays its token cost again for no new information. Read it once and refer back to what's already in context, or delegate deep digging to a subagent that reports a summary.",
      "source": null
    },
    {
      "id": "write-the-check-first",
      "kind": "unverified_edit",
      "attribution": "Generally recommended",
      "practice": "Write the check first (red/green)",
      "fix": "Add or run a check that fails first, then make the edit that turns it green — so the change is proven, not assumed. A test, a build, or a script that diffs output all work.",
      "source": null
    },
    {
      "id": "pin-tool-versions",
      "kind": "npx_unpinned",
      "attribution": "Generally recommended",
      "practice": "Pin tool versions for reproducibility",
      "fix": "Run npx pkg@<version> (not bare npx pkg) so a run is reproducible and not silently upgraded to a newer, possibly-breaking release between sessions.",
      "source": null
    }
  ]
}