gha-issue-triage AGENTS.md

Agent Instructions for gha-issue-triage

Behavioral rules and compliance requirements for AI coding agents contributing to this repository. For project overview see README.md; for integration paths and troubleshooting see docs/integrations.md; for boundary failure policies see docs/architecture.md.

Core principles (MANDATORY)

These principles override all other guidance when conflicts arise.

• KISS — simplest solution that works. Clear over clever.
• DRY — single source of truth. Reference, don't duplicate.
• YAGNI — implement only what's requested. No speculative features.
• Concise and focused — minimal code/text for task. Touch only task-related code.
• Reuse and extend — use existing patterns and dependencies. Don't rebuild.
• Root-cause and first-principles — understand the why. Solve root problems.
• Resolve ambiguity — clarify vague requirements before acting. Never assume missing context.

Behavioral rules

• Never assume missing context — ask if uncertain about requirements.
• Never hallucinate libraries — only use packages verified in pyproject.toml.
• Never delete existing code unless explicitly instructed or refactoring is documented in the PR description.
• Always confirm file paths exist before referencing in code or tests.
• Document new patterns in the PR description (not via separate sidecar files unless explicitly asked).

Repository conventions

These are non-negotiable for any PR landing on main:

• SHA-pin every uses: in workflows and action.yaml — full-length commit SHA, never a tag/branch. Enforced by repo sha_pinning_required: true policy.
• Squash-only merge — repo ruleset 15253739 allows squash exclusively.
• Required signatures — commits on main must be cryptographically signed (GPG/SSH/web-flow). CLI commits without local signing config require --admin on gh pr merge (GitHub web-flow signs the squash commit).
• Linear history — no merge commits on main.
• Required status checks — CodeFactor + CodeQL must pass before merge.
• No ${{ github.event.* }} interpolation in run: — caller inputs flow through env: and dereference as $VAR in shell. See the inline note in action.yaml.
• Use bare imports in src/ (from errors import ..., not from src.errors import ...). The action runs with PYTHONPATH=src only — there is no src package on the path at runtime. Tests can use either form (pytest pythonpath includes .).