# Project Memory

Working notes for agents on this repo. Read this alongside TODO.md
(which holds the step queue and workflow) before starting work.

## Error handling

Panicking on bad/unexpected errors is allowed and preferred over
threading unlikely error returns through game code — e.g. write-side
Close/encode failures where continuing would mean corrupt state. The
game already unwinds C's exit() calls via a gameEnd panic recovered in
Run. Return errors where a caller genuinely handles them (save-file
prompts, restore validation). Reserve deliberate `_ =` discards for
true best-effort paths (scorefile writes, signal-time autosave), always
with a comment saying why.

## Linting

The .golangci.yml is the house standard and may only be modified with
sneak's explicit permission. To disable a linter, ask, explaining what
the linter does; he approves specific exceptions, which are recorded
in the config's "Repo-specific exceptions" block with the approval
date. Approved so far: paralleltest (2026-07-06); testpackage,
exhaustive, and mnd (2026-07-07). Complexity linters (cyclop, gocognit,
nestif) stay enabled and red until refactor step 7 fixes the findings,
per sneak 2026-07-07. Line-level //nolint
with a reason is used sparingly for C-faithfulness (e.g. the authentic
"missle" message spellings) and provably-safe gosec conversions; each
needs a justifying comment.

## Faithfulness

Behavior must not change during the idiomatic-Go refactor unless a
TODO step says so. The 80x24 seed-compatible gameplay, message text
(including original typos), RNG call order, and C quirks (documented
in tests like TestHoldScrollGreedyMonsterQuirk) are contract. Doc
comments keep their "(file.c func_name)" breadcrumbs.

## Debugging

Write real, committed test files with t.Logf output and run plain
`go test -v`; no throwaway scratch scripts. Successful debug probes
become regression tests.