Structuring Deterministic Issue Templates for AI Agents

If a human engineer receives a bug ticket that reads "The user authentication route is broken, please check," they can ask follow-up questions over Slack or infer meaning by clicking around the application interface.

An AI engineering agent running within an isolated container cannot ask for clarification; it operates strictly inside a closed Reasoning-Action (ReAct) loop. If your input is ambiguous, the agent will burn its processing tokens traversing irrelevant directory trees, leading to context collapse or broken code blocks.

To achieve an unassisted agent success rate above 60%, you must treat your issue tracker — GitHub Issues or Linear — as a deterministic programming interface. Bug reports and feature specs must be delivered as structured, data-rich inputs.

Save this exact Markdown structural model into your project repository as .github/ISSUE_TEMPLATE/agent-bug-fix.md.

---
name: "🐛 [AI Agent] Deterministic Bug Resolution"
description: Structured ticket layout for automated debugging pipelines.
labels: ["agent-executable", "bug"]
assignees: ["myndboosters-bot"]
---

## 1. Context Boundary & System Environment
<!-- Explicitly declare environmental states to bypass guesswork loops -->

- **Target Subsystem / Domain:** `Authentication Services`
- **Known Relevant File Paths:**
  - `src/middleware/auth.handler.ts`
  - `src/utils/crypto.service.ts`
- **Runtime Dependency Version:** `jsonwebtoken@9.0.2`, `node@20.x`

## 2. Observable Error State (The Failure)
<!-- Provide the exact string or trace to allow the agent to match patterns precisely -->

When parsing incoming bearer tokens containing an expired epoch timestamp, the
server crashes with an unhandled exception loop instead of returning a clean
`401 Unauthorized` response array.

### Verified Console Stack Trace:

```text
TypeError: Cannot read properties of null (reading 'split')
    at TokenValidator.extractPayload (src/middleware/auth.handler.ts:42:28)
    at AuthMiddleware.handle (src/middleware/auth.handler.ts:18:34)
```

## 3. Concrete Execution Requirements (The Task)
<!-- Frame actions with deterministic imperatives: Modify, Catch, Return -->

1. **Locate** line 42 of `src/middleware/auth.handler.ts`.
2. **Implement** an explicit null-pointer guard layer evaluating the incoming
   `authorization` header string token before parsing array positions.
3. **Catch** structural token expiration errors specifically emitted by the
   `jsonwebtoken` module.
4. **Return** an explicit JSON object schema:
   `{ "error": "TokenExpired", "message": "The provided authentication token has expired." }`
   with an HTTP status header value of `401`.

## 4. Verification Gate (The Validation)
<!-- The objective criteria used by the CI/CD pipeline to evaluate success -->

- [ ] The engine must pass the localized unit-testing matrix by executing:
      `npm run test:unit -- src/middleware/auth.test.ts`
- [ ] Structural compiler verification checks must return an exit code of `0`
      via: `npm run lint`
- [ ] No files outside the `src/middleware/` directory boundary may contain
      changes or unstaged code lines.

1. Isolate one action per ticket. If a feature extension requires a database migration and a new frontend UI layout component, do not combine them into one ticket. Split them into two distinct issues. Let the agent build and test the database infrastructure first, merge that PR, and then assign the UI component ticket.
2. Keep your test matrix fast and localized. AI agents learn by testing and iterating. If your unit test suite takes 35 minutes to build and run, the agent will time out or burn through compute loops waiting on long CI runs. Ensure that small, localized test commands can run against specific files in under 30 seconds.
3. Audit and refine failed runs. When an agent fails to resolve an issue, don't just step in and manually fix the code. Look at the agent's logs, see where it lost track of the context boundary, and fix your issue template or system specifications. Treating every engineering agent failure as an optimization problem for your team's internal documentation is how you scale execution velocity without adding headcount.