coding-discipline

Coding discipline

Before editing

1. Read the nearest task, state, environment, and agent instruction files.
2. Establish the writable root and treat all deployed inputs as read-only.
3. Inspect the smallest relevant file set before proposing architecture.
4. Write a plan first when the change is broad, risky, cross-file, or poorly specified.
5. Define a measurable completion condition and the commands that will prove it.
6. For creating or finishing a GitHub repository, load github-fleet-maintenance for CI, security, documentation and artifact requirements; use release-checklist for the release handoff. A created repository or pushed code is not the complete deliverable.

During implementation

• Make one coherent change at a time.
• Preserve unrelated formatting and behavior.
• Prefer typed parsers, structured libraries, and tested transforms over regex or byte surgery.
• Keep generated output separate from source.
• Redirect large command output to a report file and summarize it.
• Stop when a required fact cannot be verified. Do not hide uncertainty behind confident prose.
• Checkpoint after each phase so a failed attempt can be reverted cleanly.

Comment what you write

Comments are non-executable text the language ignores (// or /* */, #, ; in Papyrus/INI, -- in Lua/SQL, <!-- --> in XML/HTML, '/Rem in batch/VB). Use them so a person who does not code can still follow the file:

• Top of every file: 2-4 lines on what it is for, what it needs, and where its log goes.
• Above each section or function: one plain-language line on what it does and why it exists, not a restatement of the code.
• At each non-obvious choice: the reason, the limit, or the thing that breaks if changed.
• Never comment out dead code and leave it; delete it (git keeps it). JSON has no comments; put the explanation in the README or a sibling .md.
• Keep comments true: when you change a section, change its comment in the same edit.

Anything you build also gets a toggleable debug log (observability-first) and a STATE.md recovery note (state-resumption, "Handoff for what you build").

Validation

• Review the diff, not only the final files.
• Run syntax checks, builds, tests, validators, and package inspection relevant to the task.
• Exercise failure paths and boundary cases.
• Never claim a command ran unless its output was observed.
• Report remaining risks explicitly.
• After you create a repository, push, or update a dependency, fix the cause of that repository's open Dependabot, code-scanning, and secret-scanning alerts before calling the push done. Load ci-convergence. Use TOOLS/Get-GitHubFlags.ps1 when the checkout has it; otherwise gh api those open-alert endpoints on the repository you just wrote. flags=unknown is not a clean repository. Do not dismiss an alert. Do not print a secret. A 403 or 404 on code quality is unavailable; leave it off.

Context efficiency

• Use targeted search instead of recursive reading of unrelated folders.
• Do not repeatedly reload unchanged large files.
• Persist decisions in project files, then compact or start a fresh session at a milestone.
• Use subagents only for independent exploration, audit, or testing. One owner edits a tightly coupled system.

Evidence standard

Use this hierarchy for version-sensitive facts:

1. The active project's ENVIRONMENT.md, TASK.md, installed framework version, and build files.
2. Official upstream documentation or source for that exact version.
3. Known-good files from the user's installed mod library, read-only.
4. Direct inspection of the relevant ESM, ESP, DLL, script, log, or archive.

Do not substitute memory, an old example, or a plausible token. Record the evidence path or URL in VALIDATION.md.

Claude Code execution adapter

• Keep CLAUDE.md concise and use this skill for procedural detail.
• Load only the skills needed for the current milestone because invoked skill content remains in context.
• Use high or xhigh effort for risky architecture, plugins, DLLs, and hostile review.
• Before compaction or a usage boundary, persist exact state, commands, uncommitted changes, and remaining validation.
• Treat auto memory as candidate learning, not verified truth, until it passes the memory-promotion protocol.

Skill-specific provider control

Keep each change set narrow, reversible, and linked to an explicit requirement or defect.

Usage and milestone discipline

Create the smallest buildable artifact early. Compile and checkpoint after each coherent milestone. Stop spawning subagents once the evidence is sufficient. Keep STATE.md current with exact paths, uncommitted changes, the last successful command, failures, and the next command.