Issue Documentation Template

Back to Markdown Style Guide — Read the style guide first for formatting, citation, and emoji rules.

Use this template for: Documenting bugs, feature requests, improvement proposals, incidents, or any trackable work item as a persistent markdown record. This file IS the issue — the full lifecycle from report through investigation, resolution, and lessons learned — in a format that's searchable, portable, and part of your codebase.

Key features: Classification with severity/priority, customer impact quantification, reproduction steps with expected vs actual, investigation log, resolution with root cause, acceptance criteria for feature requests, and SLA tracking.

Philosophy: This file is the source of truth for the issue — not GitHub Issues, not Jira, not Linear. Those platforms are notification and comment layers. The full lifecycle — report, investigation, root cause, fix, and lessons learned — lives HERE, committed to the repo.

An issue report is a contract between the reporter and the resolver. Vague issues get vague fixes. The best issue documents are so clear that anyone on the team — or any AI agent — could pick them up, understand the problem, and start working without asking a single clarifying question. Include everything. Assume the person reading this has zero prior context.

This is the Everything is Code philosophy: any agent or team member can find, read, and update issues with file access alone. No API, no tokens, no platform lock-in. grep docs/project/issues/ beats searching Jira every time.

File Convention

docs/project/issues/issue-00000456-fix-session-timeout-race.md
docs/project/issues/issue-00000457-add-csv-export-filtering.md
docs/project/issues/issue-00000458-improve-onboarding-copy.md

• Directory: docs/project/issues/
• Naming: issue- + issue number zero-padded to 8 digits + - + short lowercase hyphenated description
• Cross-reference: Link to the live issue tracker in the metadata table

Template Variants

This template has two variants — use the section that matches your issue type:

• Bug report — Something is broken, behaving unexpectedly, or crashing
• Feature request — Something new that should exist

Bug Report Template

Issue-[NUMBER]: [Short Description of the Bug]

📋 Summary

[One paragraph: What's broken, who's affected, and how severe the impact is. Be specific — "Users can't log in" not "auth is broken."]

Customer impact

🔄 Reproduction Steps

Environment

Steps to reproduce

1. [Exact step 1 — be precise: "Navigate to /settings/profile"]
2. [Exact step 2 — "Click the 'Save' button"]
3. [Exact step 3 — "Observe the error"]

Reproducibility: [Always / Intermittent (~N% of attempts) / Once]

Expected behavior

[What should happen when following the steps above.]

Actual behavior

[What actually happens. Include the exact error message, screenshot, or log output.]

[Paste exact error message or log output here]

Screenshot placeholder: docs/project/issues/images/issue-NUMBER-screenshot.png

Workaround

[If users can work around this bug, describe how. If no workaround exists, state "None known." This helps support teams while the fix is in progress.]

🔍 Investigation

Root cause

[What's actually causing the bug. Fill this in during investigation, not at report time.]

[If the root cause involves a data flow or logic issue, diagram it:]

flowchart TB
    accTitle: Bug Root Cause Flow
    accDescr: Diagram showing where the failure occurs in the normal processing path

    input[📥 Input] --> process[⚙️ Process]
    process --> check{🔍 Validation}
    check -->|Pass| success[✅ Expected]
    check -->|Fail| bug[❌ Bug occurs here]

    classDef bugstyle fill:#fee2e2,stroke:#dc2626,stroke-width:2px,color:#7f1d1d
    class bug bugstyle

Investigation log

[Stack traces, debug logs, database queries, config diffs — anything that supports the investigation but is too verbose for the main document.]

✅ Resolution

Fix description

[What was changed to fix the bug. Link to the PR.]

Fixed in: PR-#NUMBER

Verification

• Fix verified in [environment]
• Regression test added
• No side effects observed
• Reporter confirmed fix

Lessons learned

[What should change to prevent this class of bug? New test? Better validation? Monitoring alert? Process change?]

🔗 References

• Related issues
• Relevant documentation
• Monitoring dashboard or alert

Last updated: [Date]

Feature Request Template

Issue-[NUMBER]: [Feature Title — What Should Exist]

📋 Summary

Problem statement

[What user problem or business need does this feature address? Who experiences this problem and how often? Include metrics if available.]

Proposed solution

[High-level description of what you want built. Focus on the what and why, not the how — leave implementation details to the builder.]

User story

As a [role], I want to [action] so that [benefit].

🎯 Acceptance Criteria

The feature is complete when:

• [Specific, testable criterion — "User can export data as CSV from the dashboard"]
• [Another criterion — "Export includes all filtered results, not just the current page"]
• [Another criterion — "Download starts within 3 seconds for datasets under 10K rows"]
• [Non-functional — "Works on mobile viewport (375px+)"]
• [Documentation — "API endpoint documented in project docs"]

📐 Design

User flow

flowchart TB
    accTitle: Feature User Flow
    accDescr: Step-by-step flow showing how a user interacts with the proposed feature

    start([👤 User action]) --> step1[⚙️ System response]
    step1 --> check{🔍 Condition?}
    check -->|Yes| success[✅ Success path]
    check -->|No| alt[🔄 Alternative path]
    alt --> step1
    success --> done([📤 Result delivered])

Mockup / wireframe

[If visual, include a mockup or screenshot of the expected UI. If not visual, describe the expected behavior in detail.]

Technical considerations

• [Consideration 1]: [Impact on existing architecture, data model, or APIs]
• [Consideration 2]: [Performance, scalability, or security implications]
• [Consideration 3]: [Dependencies on other features, services, or teams]

[Deeper technical context for the implementer — suggested approach, relevant code paths, database schema changes, API contract, migration strategy. This saves the builder from discovery time.]

📊 Impact

Success metrics

[How will you know this feature is successful after shipping? Be specific and measurable.]

• [Metric 1]: [Current baseline] → [Target] within [timeframe]
• [Metric 2]: [Current baseline] → [Target] within [timeframe]

🔗 References

• User feedback or support tickets
• Competitive analysis
• Related feature requests
• Design document or ADR

Last updated: [Date]