Feedback Maintenance Runbook

Updated: 2026-07-07

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/Paperclip 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 Paperclip, 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 Paperclip or GitHub 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 Paperclip 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.

Paperclip Integration

When the Paperclip integration is configured, each new portal feedback submission should create a matching Paperclip issue and store the returned issue ID on the feedback row.

Expected behavior:

• Feedback still saves in the portal even if Paperclip is unavailable.
• A submission is only reported as fully routed when paperclip_issue_id is written. If Paperclip is unconfigured or fails, the submitter receives a degraded-routing notice and the API returns HTTP 202 with paperclipIntegration set to not_configured or failed.
• The created Paperclip issue includes submitter, type, priority, page/module, sanitized page URL, browser, screen size, optional sanitized screenshot link, and the feedback description.
• Admins should use the Paperclip issue as the execution record for engineering or operations follow-up.
• The feedback status in Bizcom should still be updated only after verification in the relevant environment.

Staging verification checklist:

1. Submit a non-sensitive staging feedback item from an authenticated staff/admin account.
2. Confirm the feedback row exists in Bizcom.
3. Confirm the row has a paperclip_issue_id.
4. Confirm a matching Paperclip issue exists with the expected title, priority, description, and project.
5. Confirm reviewer notifications still behave as expected.

If the Paperclip linkage is degraded:

1. Do not represent the submission as routed or mark it resolved.
2. Confirm the feedback row is retained and paperclip_issue_id remains null.
3. Inspect the presence (never values) of PAPERCLIP_API_URL, PAPERCLIP_API_TOKEN, and PAPERCLIP_COMPANY_ID in the target environment.
4. Restore configuration only through the approved credential/provider change path, then rerun the synthetic staging check and remove the synthetic row.

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 Paperclip issue, GitHub 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 Paperclip/GitHub reference where applicable, and a clear owner for the next action.