3.8 KiB

Raw Blame History

Step 2: Sync Bug Reports from API

MANDATORY EXECUTION RULES (READ FIRST):

🛑 NEVER generate content without user input
📖 CRITICAL: ALWAYS read the complete step file before taking any action
🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
✅ ALWAYS treat this as collaborative triage between peers
📋 YOU ARE A FACILITATOR, not an automatic processor
🌐 This step handles OPTIONAL API integration for in-app bug reporting
✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config {communication_language}

EXECUTION PROTOCOLS:

🎯 Attempt API sync only if configured
💾 Preserve existing manual input entries
📖 Format synced reports as markdown entries
🚫 FORBIDDEN to lose manually entered bugs

CONTEXT BOUNDARIES:

Variables from workflow.md are available in memory
project_url may or may not be configured
API endpoints are optional - gracefully handle if unavailable
This step can be skipped if no API integration

YOUR TASK:

Sync pending bug reports from the application's PostgreSQL database via API, formatting them as markdown entries in bugs.md.

SYNC SEQUENCE:

1. Check API Configuration

Verify {project_url} is configured:

If not configured or user skipped this step, proceed to step-03
If configured, attempt API connection

2. Fetch Pending Reports

API Call:

GET {project_url}/api/bug-reports/pending

Expected Response:

{
  "data": {
    "reports": [...],
    "count": number
  }
}

Report Fields:

id - Database ID
title - Bug title
description - Bug description
reporterType - Type of reporter (user, staff, admin)
reporterName - Name of reporter
platform - Platform (iOS, Android, web)
browser - Browser if web
pageUrl - URL where bug occurred
screenshotUrl - Optional screenshot
createdAt - Timestamp

3. Handle No Reports

If count == 0:

"No new bug reports from the application API.

[C] Continue to triage existing manual input [Q] Quit - nothing to process"

4. Format Reports as Markdown

For each report, create markdown entry:

## Bug: {title}

{description}

Reported by: {reporterName} ({reporterType})
Date: {createdAt formatted as YYYY-MM-DD}
Platform: {platform} / {browser}
Page: {pageUrl}
{if screenshotUrl: Screenshot: {screenshotUrl}}

5. Insert into bugs.md

Read the "# manual input" section location from bugs.md
Insert new markdown entries after the "# manual input" header
Preserve any existing manual input entries
Write updated bugs.md

6. Mark Reports as Synced

API Call:

POST {project_url}/api/bug-reports/mark-synced
Body: { "ids": [array of synced report IDs] }

This updates status to 'synced' so reports won't be fetched again.

7. Report Sync Results

"Synced {count} bug report(s) from application:

{for each report:}

{title} (from {reporterName}) {end for}

These have been added to the manual input section of bugs.md.

[C] Continue to parse and triage all bugs [Q] Quit"

SUCCESS METRICS:

✅ API availability checked gracefully ✅ Pending reports fetched and formatted ✅ Existing manual entries preserved ✅ Reports marked as synced in database ✅ User informed of sync results

FAILURE MODES:

❌ Crashing if API unavailable (should gracefully skip) ❌ Overwriting existing manual input entries ❌ Not marking reports as synced (causes duplicates) ❌ Proceeding without user confirmation

❌ CRITICAL: Reading only partial step file ❌ CRITICAL: Proceeding without explicit user selection

NEXT STEP:

After user selects [C], load ./step-03-parse.md to parse and identify all bugs needing triage.

Remember: Do NOT proceed until user explicitly selects [C] from the menu!

3.8 KiB Raw Blame History