Software Guidelines

Deliver a complete, reviewable change for the requested outcome. Apply this workflow to security tooling and its supporting code, from a local fix to a change spanning several modules.

Inspect the edit context

• Read applicable instructions, inspect worktree status and relevant diffs, and examine the affected implementation before editing. Identify pre-existing changes and preserve them, including in files the task also touches. Re-read changed regions if another writer may have updated them; do not reset unrelated work.
• Follow the affected entry point through relevant callers, state changes, side effects, and tests. Verify that APIs and dependencies used by the patch exist in the checked version; distinguish existing capabilities from interfaces being introduced.
• Identify the requested behavior, what must remain stable, and the smallest useful acceptance check. Use repository conventions for routine choices. If an unresolved decision changes scope, a public contract, or data integrity, use design-before-implementation; continue independent authorized work.

Make the change complete and focused

• Tie each part of the diff to the outcome or a necessary supporting change. Include required callers, tests, configuration, and documentation even when the request names only one function. Avoid unrelated features, dependency upgrades, formatting, and cleanup.
• When a symbol, signature, or data shape changes, inspect both its definition and consumers. Check indirect uses such as exports, registration strings, configuration keys, and serialized fields where relevant; a compile pass or literal-name search may miss these.
• Update the maintained source of generated artifacts and use the repository's generation workflow when required. Inspect generated changes for consistency and unrelated churn; do not patch only a derived copy that regeneration will overwrite.
• Reuse an existing convention or helper when its behavior fits. Do not reuse a similarly named abstraction without checking its error, ownership, and side-effect contracts. Add dependencies or abstractions only for a concrete requirement or boundary.
• Keep necessary validation, authorization, error propagation, and cleanup. Do not remove safeguards merely to shorten the patch or assume a failure path is impossible without establishing its preconditions.
• Allow requested simplification or a refactor needed to implement the change safely. Keep its preservation contract explicit and separate it from behavior changes where useful for review. Load software-architecture, then its simplification reference when making those structural or readability decisions.
• Remove imports, parameters, helpers, and temporary diagnostics made obsolete by this change. Leave unrelated pre-existing cleanup for a separately scoped task; mention it only when it affects the outcome or poses a material risk.