Bug Report Template for AI-Assisted Development
The AI-optimized bug report template: AI rule: 'Bug reports include: 1) Title: [area] brief description (e.g., [auth] login fails with expired session token). 2) Current behavior: what happens now (with error message if applicable). 3) Expected behavior: what should happen instead. 4) Steps to reproduce: numbered list, specific and complete. 5) Environment: browser, OS, app version. 6) Affected files (optional): the files where the bug likely exists. 7) Related tests: existing test files that should cover this behavior.' The template: provides the AI with enough context to locate and fix the bug.
Why the affected files field matters for AI tools: when a developer pastes a bug report into an AI session, the affected files field tells the AI exactly where to look. Without it: the AI searches the entire codebase. With it: 'Bug in src/features/auth/auth.service.ts — the session expiry check does not account for timezone differences.' The AI: opens the file, reads the function, and generates a targeted fix. The affected files field: reduces AI debugging time from 5-10 prompts to 1-2 prompts.
Related tests field: AI rule: 'Every bug report references the test file that should have caught the bug. If no test exists: note 'No existing test — add test with fix.' The AI: reads the related test, understands the expected behavior, and generates both the fix and the additional test case. The test: prevents the bug from recurring. The bug-fix-test cycle: automated by providing the AI with the test context upfront.' AI rule: 'Bug report templates serve two purposes: documenting the issue for humans and providing context for AI tools. The traditional fields (description, steps to reproduce) serve humans. The AI-specific fields (affected files, related tests) serve AI tools. Both: in the same template.'
Feature Request Template for AI-Assisted Development
The AI-optimized feature request template: AI rule: 'Feature requests include: 1) Title: brief description of the feature. 2) User story: As a [role], I want [capability], so that [benefit]. 3) Acceptance criteria: numbered list of specific, testable conditions that define done. 4) UI/UX description (if applicable): what the user sees and interacts with. 5) API changes (if applicable): new endpoints, modified responses, new parameters. 6) Related features: existing features this new feature interacts with. 7) Out of scope: what this feature explicitly does NOT include.' The template: gives the AI everything it needs to implement the feature.
Acceptance criteria that AI tools can implement: AI rule: 'Acceptance criteria must be specific and testable. Bad: The notification system works well. Good: 1) Users can enable/disable notifications per channel (email, push, in-app). 2) Disabled channels do not receive notifications. 3) Changes persist across sessions. 4) Default: all channels enabled for new users. 5) API returns 400 if channel type is invalid. Each criterion: translatable to a test case. The AI: generates one test per criterion and implements code that passes all tests.' The specificity: determines whether the AI generates a complete implementation or a partial one that requires multiple rounds of refinement.
Out of scope field: AI rule: 'Every feature request lists what is out of scope. Example: Out of scope: notification scheduling (future feature), notification analytics (separate ticket), email template customization (design team dependency). The out of scope: prevents the AI from over-engineering the feature. Without it: the AI may add scheduling logic, analytics tracking, or template customization because they seem logically related. With it: the AI implements exactly what is requested and nothing more.' AI rule: 'Feature request templates determine AI implementation quality. Vague requests produce vague implementations requiring multiple refinement rounds. Specific requests with acceptance criteria produce complete implementations in one generation session. The template: makes the difference.'
Feature request acceptance criterion: 'Users can enable/disable notifications per channel (email, push, in-app).' The AI reads this and generates: it('should enable email notifications when user toggles email channel on'). it('should disable push notifications when user toggles push channel off'). it('should persist channel preferences across sessions'). Each criterion: one or more test cases. Five criteria: 5-10 tests. The AI generates the tests from the criteria, then implements the code that passes them. The acceptance criteria: not just PM requirements — they are test specifications that the AI converts directly into code.
Technical Task Template
The technical task template: AI rule: 'Technical tasks (refactoring, infrastructure, tech debt) include: 1) Title: brief description. 2) Motivation: why this task needs to be done now. 3) Current state: how things work today. 4) Target state: how things should work after the task. 5) Approach: suggested implementation approach (the developer can deviate if they find a better way). 6) Files to modify: list of files that will be changed. 7) Verification: how to verify the task is complete (tests, benchmarks, manual checks). 8) Risks: what could go wrong.' The template: provides the AI with the full context for technical changes.
Current state vs target state: this pair is the most valuable template field for AI tools. AI rule: 'Current state: describe the current implementation with specific details. Example: Currently, the auth middleware checks session expiry using Date.now() which does not account for server timezone. Target state: The auth middleware checks session expiry using UTC timestamps, and all session timestamps are stored in UTC.' The AI: understands exactly what to change and why. The diff: from current to target is clear. Without this pair: the AI guesses what 'fix the timezone issue' means.
Risks field: AI rule: 'The risks field documents what could go wrong if the task is implemented incorrectly. Example: Risk: Changing the timestamp format could invalidate all existing sessions, logging out all users. Mitigation: Add a migration that converts existing timestamps to UTC before deploying the code change.' The AI: reads the risks and generates implementation that avoids them. Without the risks field: the AI generates a fix that works correctly but causes a mass logout because it did not know about existing sessions. AI rule: 'Technical task templates prevent the AI from solving the immediate problem while creating a new one. The risks field: the critical addition that makes AI-generated technical changes safe. The current/target state pair: the critical addition that makes them accurate.'
Feature request: 'Add notification preferences.' Without out-of-scope: the AI generates notification preferences + notification scheduling + notification analytics + email template customization. The PR: 800 lines instead of 200. The review: 3 hours instead of 45 minutes. The scope: 4x what was requested. With out-of-scope: 'Out of scope: scheduling, analytics, email templates.' The AI generates: notification preferences only. 200 lines. 45-minute review. Exactly what was requested. The out-of-scope field: costs 30 seconds to write, saves hours of review and potential rework.
Integrating Issue Templates with AI Workflows
Issue-to-prompt conversion: AI rule: 'When starting work on an issue: paste the issue content into the AI session as context. The template fields: map directly to prompt context. User story → feature description. Acceptance criteria → test specification. Affected files → file context. The issue template: designed to be copy-pasted into an AI session without reformatting.' The template: serves double duty — project management documentation and AI prompt context. The developer: copies the issue, pastes it into Claude Code, and starts generating.
Labeling for AI workflow routing: AI rule: 'Issue labels include AI workflow indicators. Labels: ai-ready (issue has enough detail for AI generation), needs-spec (issue needs more detail before AI generation), manual-only (issue requires human judgment, not suitable for AI generation). The ai-ready label: signals that the issue template is complete enough for a developer to paste into an AI session and get a useful implementation. The needs-spec label: signals that the issue needs refinement before AI-assisted work begins.' The labels: help developers prioritize which issues to tackle with AI tools.
Template validation: AI rule: 'Issues missing required fields: flagged by the issue tracker bot. Bug reports without steps to reproduce: auto-labeled needs-info. Feature requests without acceptance criteria: auto-labeled needs-spec. The validation: ensures every issue has enough context for AI-assisted implementation before a developer starts working on it. An incomplete issue → incomplete AI prompt → incomplete implementation → multiple revision rounds. A complete issue → complete AI prompt → complete implementation → one review round.' AI rule: 'Issue template integration closes the loop between project management and AI-assisted development. The PM writes the issue. The developer pastes it into the AI. The AI generates the implementation. The template: the bridge that makes this workflow possible.'
Issue: 'Fix the login bug.' No steps to reproduce. No affected files. No expected behavior. The developer: pastes this into the AI session. The AI: 'Which login bug? What is the expected behavior? What files are involved?' The developer: spends 15 minutes providing context that should have been in the issue. Then the AI: generates a fix for the wrong login bug (there are 3 open login issues). Template validation: issues without required fields get auto-labeled needs-info. The developer: never starts AI-assisted work on an incomplete issue. One validation rule: prevents hours of misdirected AI generation.
Issue Template Quick Reference
Quick reference for AI coding issue templates.
- Bug report: title with area, current vs expected behavior, steps to reproduce, affected files, related tests
- Feature request: user story, acceptance criteria (specific + testable), UI/API changes, out of scope
- Technical task: motivation, current state, target state, approach, files to modify, risks with mitigations
- AI-specific fields: affected files (tells AI where to look), related tests (tells AI what to test), out of scope (prevents over-engineering)
- Acceptance criteria: one criterion per test case — the AI generates tests directly from criteria
- Issue-to-prompt: templates designed to be copy-pasted into AI sessions without reformatting
- Labels: ai-ready (complete), needs-spec (incomplete), manual-only (not suitable for AI)
- Validation: bot flags incomplete issues — ensures AI has enough context before work begins