Bug Triage System — Customization Guide

How to adapt the Bug Triage & Issue Tracker to your team's workflow, scale, and tooling.

Table of Contents

1. Adjusting Severity Levels & SLA Targets

2. Customizing the Status Workflow

3. Adding Custom Properties

4. Scaling for Different Team Sizes

5. Integrating with External Tools

6. Setting Up Automations

7. Creating Custom Views

8. Multi-Product / Multi-Team Setup

Adjusting Severity Levels & SLA Targets

The default system uses 4 severity levels. You can modify these to match your organization's standards.

Changing SLA Targets

1. Open the Severity Matrix page (pages/severity-matrix.md).

2. Update the SLA targets in the reference table.

3. Update the SLA Status formula in the Bugs database (see formulas/FORMULAS.md) to match your new thresholds.

Example — Startup with aggressive SLAs:

Example — Enterprise with business-hours SLAs:

Adding a 5th Severity Level

If you need a "Cosmetic / Trivial" level below S4:

1. Add "S5 — Trivial" to the Severity Select property on the Bugs database.

2. Update the Priority Matrix to include the new row.

3. Update formulas that reference severity values.

Customizing the Status Workflow

Simplifying the Workflow (Small Teams)

If your team is 1-3 people, the full 8-status workflow may be overkill. Simplify to:

New → In Progress → Resolved → Closed

1. Edit the Status Select property — remove statuses you don't need.

2. Update the Board view to reflect fewer columns.

3. Update the SLA Status formula if it references removed statuses.

Adding Statuses (Larger Teams)

Common additions:

To add: Edit the Status Select property → add new options with appropriate colors.

Adding Custom Properties

Customer-Reported Flag

Add a Checkbox property called "Customer Reported" to the Bugs database. This lets you:

• Filter views to show only customer-facing bugs.
• Track customer-reported vs. internally-found bug ratios.
• Prioritize customer-impacting issues in triage.

Environment Tags

Replace the single "Environment" Select with a Multi-select if bugs appear in multiple environments:

• Production, Staging, Development, CI/CD, Local

Affected Version

Add a Select property called "Affected Version" (e.g., v2.3.1, v2.4.0). Useful for:

• Release regression tracking.
• Knowing which version to test fixes against.

Customer Impact Count

Add a Number property called "Customers Affected". This helps prioritize by business impact:

• 1-10: Individual reports
• 10-100: Significant segment
• 100+: Widespread issue, escalate to S1

Linked PR / Commit

Add a URL property called "Fix PR URL". Link directly to the GitHub/GitLab pull request that fixes the bug. Useful for:

• Code review traceability.
• Quick access to the fix from the bug tracker.

Scaling for Different Team Sizes

Solo Developer (1 person)

Simplify aggressively:

• Remove the Team Members database (you're the only member).
• Remove the Sprints database (use a simple "This Week / Next Week / Backlog" Select instead).
• Keep: Bugs, Components, Root Causes.
• Use 3 statuses: Open → In Progress → Done.
• Skip the triage meeting — just review your bug list daily.

Small Team (2-5 people)

Use the system mostly as-is, with tweaks:

• Keep all databases.
• Simplify Sprints to 2-week cycles.
• Each person creates a "My Bugs" filtered view.
• Hold a 15-minute triage meeting twice per week.

Medium Team (5-15 people)

Add structure:

• Add a "Team" Select to the Bugs database (Backend, Frontend, Mobile, Platform).
• Create team-specific Board views filtered by Team.
• Designate a Triage Lead who runs the weekly triage meeting.
• Add a "Reviewed By" Relation to track who triaged each bug.

Large Team (15-50+ people)

Add hierarchy and automation:

• Create separate Bugs databases per product area (or use the "Team" property with strict filtered views).
• Add a "Triage Queue" view — sorted by Reported Date, filtered to Status = New.
• Add escalation rules: If an S1 bug is not assigned within 1 hour, auto-notify the team lead.
• Consider linking to an external tracker (Jira, Linear) for cross-team visibility.
• Use Notion API automations to sync status changes.

Integrating with External Tools

GitHub Issues (Manual Linking)

1. Add a URL property called "GitHub Issue" to the Bugs database.

2. When filing a bug, paste the corresponding GitHub issue URL.

3. Use Notion's web clipper to pull GitHub issue content into the bug's page body.

GitHub Issues (Automated Sync via Notion API)

1. Use the Notion API to create a bug entry when a GitHub issue is labeled bug.

2. Webhook flow: GitHub → webhook → your server → Notion API POST /pages.

3. Map fields: GitHub title → Bug Title, GitHub labels → Severity/Tags, GitHub assignee → Assignee.

Linear / Jira (Bidirectional)

For two-way sync with Linear or Jira:

1. Use Zapier or Make.com as the integration bridge.

2. Trigger: "New item in Notion Bugs database" → Create issue in Linear/Jira.

3. Trigger: "Issue status changed in Linear/Jira" → Update Status in Notion.

4. Map severity and priority values between systems.

Slack Notifications

1. Use Notion's built-in Slack integration (Settings → Connections → Slack).

2. Or create a Zapier automation: "New bug with Severity = S1" → Post to #engineering-alerts.

3. Include: Bug ID, Title, Severity, Component, Assignee.

PagerDuty (S1 Escalation)

For critical bugs that need immediate on-call response:

1. Zapier trigger: "New bug in Notion where Severity = S1 — Critical".

2. Action: Create PagerDuty incident with bug title and link.

Setting Up Automations

Notion Built-in Automations (Pro Plan)

Notion Pro includes database automations. Set up these useful rules:

Auto-assign to triage queue:

• Trigger: New page added to Bugs database
• Action: Set Status to "New", set "Needs Triage" checkbox to true

SLA reminder:

• Trigger: SLA Deadline property is "today"
• Action: Send notification to Assignee

Auto-close stale bugs:

• Trigger: Status = "Resolved" AND last edited > 14 days ago
• Action: Set Status to "Closed"

Notion API Automations (Custom)

For advanced automation, use the Notion API with a cron job or serverless function:

# Pseudocode: Flag overdue bugs
1. Query Bugs database where Status NOT IN (Resolved, Closed, Verified)
2. For each bug, compare SLA Deadline to current date
3. If overdue, update a "SLA Breached" checkbox to true
4. Send Slack notification with list of breached bugs

Creating Custom Views

"Overdue Bugs" View

1. Create a new Table view.

2. Filter: SLA Deadline < Today AND Status NOT IN (Resolved, Verified, Closed).

3. Sort: SLA Deadline ascending (most overdue first).

4. Color-code by severity.

"Unassigned Bugs" View

1. Create a new Table view.

2. Filter: Assigned To is empty AND Status = "New" or "Triaged".

3. Sort: Priority ascending.

4. This is the triage lead's primary working view.

"Component Health" View (on Components database)

1. Create a Board view on the Components database.

2. Group by: Criticality.

3. Show the "Active Bug Count" rollup prominently.

4. Components with high bug counts in the Critical column need attention.

"Sprint Burndown" View (on Sprints database)

1. Create a Table view on the Sprints database.

2. Show: Sprint, Status, Bugs Assigned, Bugs Resolved, and a formula for completion %.

3. Filter: Status = "Active".

4. This gives a quick sprint progress snapshot.

Multi-Product / Multi-Team Setup

If your organization has multiple products or teams sharing one bug tracker:

Option A: Single Database with Filters

• Add a "Product" Select property (e.g., "Web App", "Mobile App", "API", "Admin Panel").
• Create filtered views per product.
• Pros: Single source of truth, easy cross-product queries.
• Cons: Database gets large; permissions are all-or-nothing.

Option B: Separate Databases per Product

• Duplicate the entire Bug Triage System for each product.
• Share the Team Members and Components databases across products using relations.
• Pros: Clean separation, team-specific customization.
• Cons: Harder to see cross-product trends.

Recommendation

Start with Option A (single database) until you exceed ~500 bugs or 3 products. Then split to Option B. Notion handles hundreds of entries well, but thousands can slow down views.

Tips for Long-Term Success

1. Archive resolved bugs quarterly. Move bugs with Status = "Closed" older than 90 days to an "Archive" database. This keeps your active database fast.

2. Review root causes monthly. Sort the Root Causes database by Occurrence Count. The top 3 categories tell you where to invest in prevention.

3. Rotate the triage lead. Don't let one person own triage forever. Rotate weekly so the whole team understands the bug landscape.

4. Track your SLA hit rate. Create a formula that calculates (bugs resolved within SLA) / (total bugs resolved). Target 90%+ for S1 and S2.

5. Link bugs to postmortems. For every S1 bug, create a postmortem page (use the template in templates/) and link it to the bug entry. This builds institutional knowledge.

*Questions? Contact [email protected]*