Feedback Maintenance Runbook

Updated: 2026-05-02

Purpose

Keep the Bizcom feedback board actionable so stale, already-shipped, duplicate, or product-decision items do not hide current operational problems.

This runbook covers:

• Production feedback board: https://bizcom.ph/admin/feedback
• Staging feedback board: https://staging.bizcom.ph/admin/feedback
• Admin API route used by the UI: /api/admin/feedback
• GitHub/Linear verification before changing statuses
• Documentation updates when workflow behavior changes

Safety Rules

• Treat production feedback as live operational data.
• Do not bulk-mark feedback resolved.
• Do not mutate production feedback without explicit approval.
• Do not paste passwords, tokens, private client files, bank details, government IDs, or confidential client data into Linear, GitHub, Discord, or docs.
• If a feedback item references sensitive evidence, record only the safe summary and keep the evidence in the approved private path.

Feedback Statuses

Status	Use When
new	Not reviewed yet.
acknowledged	Reviewed, understood, and waiting for prioritization or verification.
in_progress	Active branch, PR, design packet, or implementation work exists.
resolved	Verified fixed or implemented in the target environment.
dismissed	Duplicate, obsolete, invalid, intentionally not prioritized, or superseded.

Status updates are performed through:

• PATCH /api/admin/feedback/:id with { status } or { status, adminNotes }

Required Review Fields

For each meaningful feedback item, capture:

• Type: bug, feature request, data issue, workflow confusion, duplicate, or obsolete item.
• Environment: production, staging, or unknown.
• Severity / work impact.
• Module/page and URL.
• Expected vs actual behavior.
• Sensitive-data risk.
• Current status.
• Evidence supporting any status change.
• Existing Linear issue, if one exists.
• Whether Alex needs to make a product/business decision.

Verification Before Changing Status

Mark acknowledged only if

• An admin has read the item and it is valid enough to keep; and
• The next step is known, even if not scheduled.

Mark in_progress only if

• An open branch/PR exists; or
• A Linear issue/design packet is actively being worked; or
• Active implementation work is documented.

Mark resolved only if

• The fix is verified in production; or
• Alex explicitly accepts staging validation as sufficient for that item; or
• A release note/PR smoke test clearly proves the target environment now behaves correctly.

Mark dismissed only if

• It is a duplicate of another tracked item.
• It is obsolete or no longer relevant.
• It is not reproducible and not actionable.
• It is superseded by a newer feedback item or product decision.

Staging vs Production

• Use staging for QA smoke tests, structured feedback validation, and release candidate verification.
• Use production read-only audits to understand live operational state.
• Do not copy staging smoke-test feedback into production.
• Do not mark production items resolved because staging works unless that release is already promoted or Alex explicitly approves the cleanup.

Current Verified State — 2026-05-02

• OPS-112 structured feedback / Report Issue / Suggest Feature flow is implemented on staging via PR #180.
• Staff-side staging smoke passed with structured feedback item ef9a3272-36e6-4e11-8c6c-aae62da5ce56.
• Admin/owner staging smoke confirmed the admin feedback page loads, the structured item appears, and structured fields display in the detail panel.
• Staff access to the admin feedback page/API remains restricted.
• OPS-112 should remain in Review until Alex approves production promotion; do not deploy production from this runbook.

Nightly / Weekly Maintenance Output

Each maintenance pass should record:

• Number of feedback items reviewed.
• Item classification and recommended action.
• Related Linear issue or PR.
• Whether the item is verified in staging or production.
• Whether any production status was changed.
• Whether Alex approval is needed.
• Docs or runbook updates made.

Status Write-Back Path

• scripts/fetch-feedback.sh fetches production feedback JSON.
• scripts/update-feedback-status.mjs performs explicit authenticated status updates through the admin API.
• Status write-back must remain separate from read-only fetches.
• If local helper paths regress, prefer a portable Node/Python parser over a machine-specific binary path.

Recommendation

Keep feedback board hygiene as a distinct tracked workflow. Do not treat it as an automatic side effect of code fixes. Each status change should have evidence, a Linear/GitHub reference where applicable, and a clear owner for the next action.