Skip to content

AGENTS.md — add plain-language explanation rule (and flag the open tx.accountCode question)

Why (owner, 2026-06-23)

In a tx-diagnosis session (lookup of tx 9zVOyZ6AggDJaSpKqD25), the agent's explanation leaned on technical names without plain-English framing — terms like "the V1 adapter", "InvoiceAllocations shape", and "the GL_REVENUE_RESTRICTED invariant" appeared without first saying in everyday words what those names refer to and what would change. Owner cited a prior task UID (T-075) as if its meaning were self-evident; it wasn't. Owner is fine reading function and file names, but the explanation itself must lead in plain language; the names are for navigation, not narration. Adding this as a Working-agreements rule so the next agent doesn't repeat the mistake.

What changed in this task

  • AGENTS.md → Working agreements → new bullet "Plain language first; technical names in parens." inserted as the first bullet of the section so it applies to every interaction (commit: see PR / branch this lands on).
  • docs/eop-tasks/README.md → next-free pointer bumped past this task's UID. (Originally claimed T-092; renumbered to T-097 at merge time after a parallel-agent T-092 collision — see Log. The README pointer has since been bumped further as later tasks landed; check README.md for the current next-free.)

Spillover from the same session — NOT in this task

The diagnosis surfaced a separate disagreement the owner wants reviewed before any code change:

  • A previous change (T-075, PR #762) decided that for income transactions, the GL-account-code field on the transaction document would be left empty, and the GL would only be reachable through a new "effective GL codes" list on the in-app transaction object. The owner does not recall agreeing to that and still considers the GL-account-code field significant on the tx doc — same field, same meaning, for both income and expense txs.
  • Practical effect of the previous design: income txs (e.g. 9zVOyZ6AggDJaSpKqD25 — an HKD 9,500 cheque deposit matched to two ERL invoices summing to 9,500) show no GL in most UI surfaces even though the journal still posts to GL 4000 correctly.
  • Direction the owner is leaning: re-populate the GL-account-code field on income txs in the read-side adapter (set it to "4000" when the transaction has matched-invoice allocations under gl["4000"], and "4001" for coaching), so every existing display site "just works" with no further code changes. Single-point fix in lib/accounting/transactionAdapter.ts. No data migration needed (read-side only). Awaiting owner's go-ahead before the fix opens its own task.

Log

  • 2026-06-23 created + closed in the same edit (housekeeping for the AGENTS.md rule). Spillover left open above as a marker for the follow-up conversation; if owner confirms the direction, open a separate T-NNN for the adapter fix and cross-link here. Source: Accounting (Diagnostics) · https://claude.ai/code/session_01G58Y71noihrYCDEDMexmea
  • 2026-06-23 spillover resolved → T-093 opened for the read-side adapter fix (owner confirmed direction after researching the back story of T-075 + the getAccountCodeFromGL skip rule). T-075's log also updated with the reversal pointer so the board is honest about what changed. Source: Accounting (Diagnostics) · https://claude.ai/code/session_01G58Y71noihrYCDEDMexmea
  • 2026-06-23 RENUMBERED T-092 → T-097 at merge time. Records-team agents shipped a font/color refinement under T-092 (PRs #788/#789) to main + nightly while this branch was open, so both T-092s ended up claiming the same UID. Per AGENTS.md's "renumber on merge, per PR" rule, this branch (the second to merge) renumbers. Both main + nightly's next-free already sat at T-097, so T-097 is the actual next-free for this work. Cross-refs in T-093.md (this PR) updated; T-075.md's log only references T-093 (no change). Commit messages on this branch keep their original (t-092) prefixes per AGENTS.md's "commit messages stay as-is" rule. Source: Accounting (Diagnostics) · https://claude.ai/code/session_01G58Y71noihrYCDEDMexmea

Commit index (backfilled 2026-07-01, best-effort · Coaching (Diagnostic))

Candidate related commits, auto-backfilled from git on main: commits whose message references this task's UID or a PR number it cites. Not verified — this squash-merged history can't yield a precise per-task list, so rows tagged (mentions only) name the task in passing (may be tangential) and untagged work commits may be missing. Treat as a starting point: verify, prune tangential rows, and append any real ones per the AGENTS.md "record every related SHA" policy.

  • (no git-discoverable commit references this UID or its PRs — append real SHAs here as identified.)