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 support@datanest.dev*

Bug Triage System — Notion Import Guide

Step-by-step instructions for importing and configuring the Bug Triage & Issue Tracker in Notion.

Prerequisites

• A Notion account (Free plan works; Pro recommended for Timeline views and automations)
• A dedicated Notion workspace or page where you want the system to live
• The 5 CSV files from the databases/ folder
• 20-30 minutes for initial setup

Step 1: Create Your Workspace Page

1. In Notion, create a new page called "Bug Triage System" (or your preferred name).

2. Add an icon (suggested: 🐛) and a cover image.

3. This page will be the parent for all databases and sub-pages.

Step 2: Import the Databases

Import each CSV file as a new database inside your workspace page. Order matters — import in this sequence so relations can reference existing databases.

2.1 Import components.csv

1. Inside your workspace page, click "/" → "Import" → "CSV".

2. Select databases/components.csv.

3. Notion creates a new database. Rename it to "Components".

4. Set property types:

5. Add a Select color scheme for Criticality:

• Critical → Red
• High → Orange
• Medium → Yellow
• Low → Gray

2.2 Import team-members.csv

1. Click "/" → "Import" → "CSV" inside the workspace page.

2. Select databases/team-members.csv.

3. Rename the database to "Team Members".

4. Set property types:

5. Add a Select color scheme for Availability:

• Available → Green
• Partial → Yellow
• On Leave → Red

2.3 Import sprints.csv

1. Import databases/sprints.csv into the workspace page.

2. Rename to "Sprints".

3. Set property types:

4. Select colors for Status:

• Completed → Green
• Active → Blue
• Planned → Gray

2.4 Import root-causes.csv

1. Import databases/root-causes.csv.

2. Rename to "Root Causes".

3. Set property types:

2.5 Import bugs.csv (Main Database)

1. Import databases/bugs.csv.

2. Rename to "Bugs".

3. Set property types:

4. Select colors for Severity:

• S1 — Critical → Red
• S2 — High → Orange
• S3 — Medium → Yellow
• S4 — Low → Gray

5. Select colors for Priority:

• P0 → Red
• P1 → Orange
• P2 → Yellow
• P3 → Light Gray
• P4 → Default

6. Select colors for Status:

• New → Light Gray
• Triaged → Blue
• Assigned → Purple
• In Progress → Yellow
• In Review → Orange
• Resolved → Green
• Verified → Dark Green
• Closed → Gray
• Reopened → Red

Step 3: Create Relations Between Databases

Now link the Bugs database to the supporting databases.

3.1 Bugs → Components Relation

1. Open the Bugs database.

2. Click "+" to add a new property.

3. Choose "Relation" → select "Components" database.

4. Name the property "Component (Linked)".

5. For each bug, click the Component (Linked) cell and select the matching component.

6. (Optional) Delete the old text-based "Component" column once all bugs are linked.

3.2 Bugs → Team Members Relation

1. Add a new Relation property pointing to "Team Members".

2. Name it "Assigned To".

3. Link each bug to the correct team member.

4. (Optional) Delete the old "Assignee" text column.

3.3 Bugs → Sprints Relation

1. Add a new Relation property pointing to "Sprints".

2. Name it "Sprint (Linked)".

3. Link each bug to its sprint.

4. (Optional) Delete the old "Sprint" text column.

3.4 Bugs → Root Causes Relation

1. Add a new Relation property pointing to "Root Causes".

2. Name it "Root Cause (Linked)".

3. Link each resolved/triaged bug to its root cause category.

4. (Optional) Delete the old "Root Cause" text column.

Step 4: Add Rollup Properties

Rollups aggregate data from related databases. These power your dashboard metrics.

On the Components Database

1. Add a Rollup property called "Active Bug Count".

• Relation: the reverse relation from Bugs → Components
• Property: Title
• Calculate: Count all
• This shows how many bugs each component currently has.

2. Add a Rollup property called "Critical Bug Count".

• Relation: reverse relation from Bugs
• Property: Severity
• Calculate: Count values → then filter for "S1 — Critical"
• (Alternatively, use a formula on the Bugs count filtered by severity.)

On the Team Members Database

1. Add a Rollup property called "Assigned Bugs".

• Relation: reverse relation from Bugs → Team Members
• Property: Title
• Calculate: Count all

2. Add a Rollup property called "At Capacity?".

• Create a Formula property (see formulas/FORMULAS.md for the exact formula).
• Compares Assigned Bugs rollup to Max Capacity.

On the Sprints Database

1. Add a Rollup property called "Bugs in Sprint".

• Relation: reverse relation from Bugs → Sprints
• Property: Title
• Calculate: Count all

2. Add a Rollup property called "Resolved in Sprint".

• Relation: reverse relation from Bugs
• Property: Status
• Calculate: Count values → count entries where Status = "Resolved" or "Verified" or "Closed"

Step 5: Set Up Views on the Bugs Database

Create multiple views to support different workflows.

5.1 Board View — "Triage Board"

1. Open the Bugs database → click "+" next to the current view tab → "Board".

2. Name it "Triage Board".

3. Group by: Status.

4. The columns will be: New | Triaged | Assigned | In Progress | In Review | Resolved | Verified | Closed.

5. Drag bugs between columns to update their status.

6. Sub-group by: Severity (optional — shows severity bands within each column).

5.2 Table View — "All Bugs"

1. Add a new Table view called "All Bugs".

2. Show columns: Bug ID, Title, Severity, Priority, Status, Assigned To, Component (Linked), Sprint (Linked), SLA Deadline.

3. Sort by: Priority (ascending), then Reported Date (ascending).

4. This is your master reference view.

5.3 Table View — "My Bugs" (Filtered)

1. Add a new Table view called "My Bugs".

2. Add a Filter: Assigned To → contains → [your name].

3. Sort by: Priority ascending.

4. Each team member creates their own "My Bugs" view.

5.4 Board View — "By Severity"

1. Add a new Board view called "By Severity".

2. Group by: Severity.

3. Columns: S1 — Critical | S2 — High | S3 — Medium | S4 — Low.

4. Useful for triage meetings to see the severity distribution at a glance.

5.5 Calendar View — "SLA Deadlines"

1. Add a new Calendar view called "SLA Deadlines".

2. Date property: SLA Deadline.

3. This shows upcoming SLA deadlines on a calendar. Red cards = overdue.

5.6 Timeline View — "Sprint Timeline" (Requires Notion Pro)

1. Add a new Timeline view called "Sprint Timeline".

2. Timeline by: Reported Date → SLA Deadline (or Resolution Date).

3. Group by: Sprint (Linked).

4. This shows bug lifecycles across sprints.

Step 6: Create Dashboard and Reference Pages

Copy the content from the pages/ folder into new Notion pages inside your workspace.

1. Triage Dashboard (pages/triage-dashboard.md)

• Create a new page called "Triage Dashboard" inside your workspace.
• Paste the markdown content.
• Replace the placeholder database references with linked views of your actual Bugs database.
• To add a linked database view: type /linked → "Linked view of database" → select your Bugs database → choose the view.

2. Severity Matrix (pages/severity-matrix.md)

• Create a new page called "Severity & Priority Matrix".
• Paste the content. This is a reference page — no database links needed.

3. SLA Policy (pages/sla-policy.md)

• Create a new page called "SLA Policy".
• Paste the content. Update the SLA targets if your team uses different thresholds.

Step 7: Add Bug Report Templates

1. Open the Bugs database.

2. Click the dropdown arrow next to the blue "New" button → "+ New template".

3. Create templates from the templates/ folder:

• Bug Report Template (templates/bug-report-template.md):
• Name the template "Bug Report".
• Set default property values: Status = "New", Environment = "Production".
• Paste the template body content into the page body.

• Reproduction Steps Template (templates/reproduction-steps-template.md):
• Name the template "Reproduction Steps".
• This is a detailed template for complex bugs that need thorough reproduction documentation.

4. Now when any team member clicks "New" in the Bugs database, they can choose the template.

Step 8: Add Formula Properties

See formulas/FORMULAS.md for the complete list of formulas. Add these as Formula properties on the Bugs database:

1. SLA Status — Shows "On Track", "At Risk", or "Breached" based on current date vs. SLA Deadline.

2. Age (Days) — Number of days since the bug was reported.

3. Priority Score — Numeric score for sorting (lower = more urgent).

4. Resolution Time — Days between Reported Date and Resolution Date (for resolved bugs).

Step 9: Final Checks

• [ ] All 5 databases imported and renamed
• [ ] Relations created between Bugs ↔ Components, Team Members, Sprints, Root Causes
• [ ] Rollup properties added on Components, Team Members, and Sprints
• [ ] At least 4 views created on the Bugs database (Triage Board, All Bugs, By Severity, SLA Deadlines)
• [ ] Dashboard page created with linked database views
• [ ] Severity Matrix and SLA Policy pages created
• [ ] Bug Report and Reproduction Steps templates added to the Bugs database
• [ ] Formula properties added (SLA Status, Age, Priority Score)

Troubleshooting

CSV import creates wrong property types:

Notion sometimes guesses incorrectly. After import, click the property header → "Edit property" → change the type. Data is preserved in most cases.

Relations don't show the right items:

Make sure the relation points to the correct database. If you renamed a database after creating the relation, the relation still works — but double-check by clicking it.

Rollups show "No results":

Rollups only work when the relation has linked entries. Make sure you've linked bugs to components/team members before expecting rollup values.

Formula errors:

Copy formulas exactly from formulas/FORMULAS.md. Notion formulas are case-sensitive and whitespace-sensitive. If a property name has spaces, wrap it in prop("Property Name").

*Need help? Contact support@datanest.dev*