Automated Code-Brief Drift Detection Workflow: Grok Bot / Claude Coordination and Triage Protocol

Summary

This issue documents a recurring process failure mode in which generated code diverges from specification briefs without triggering a blocking review. A two-agent pipeline — Grok Bot (read-only static analyzer) and Claude (fix owner) — is intended to catch and resolve this drift on a version-by-version basis. The practical impact is that unflagged drift can silently accumulate across version stamps, causing production behavior to diverge from the intended specification.

Root-Cause Analysis

Important caveat: The technical input supplied contains no concrete error messages, stack traces, log output, or configuration artifacts. The diagnosis below is based solely on the workflow description provided. The actual root cause of any specific version-stamped finding cannot be determined from this evidence alone.

What can be reasonably inferred

Confirmed from supplied evidence:

• A code-to-brief comparison mechanism (Grok Bot) exists and operates in read-only mode against the repository tree.
• Findings are version-stamped (e.g., v2393, v2394) and queued to this issue rather than applied automatically.
• Claude is designated as the sole agent with write authority over fixes and deployments.
• Issue #4 (/api/board_tick) is closed and must not be reopened; it represents a resolved or deprecated concern.
• Issue #3 (HE briefs / live looks) is a separate, non-backend queue and must not receive backend findings.

Reasonable inference:

• The primary failure mode this workflow guards against is specification drift: code being shipped that no longer matches the current brief, likely introduced by iterative edits, AI-assisted generation, or merge conflicts.
• A secondary failure mode is queue contamination: findings being posted to the wrong issue (#3 vs. this issue), which degrades the signal-to-noise ratio and slows remediation.
• The explicit prohibition on reopening #4 suggests that /api/board_tick was previously a source of noisy or misdirected findings.

Cannot be determined without additional evidence:

• Which specific version stamps currently have open findings.
• The nature, severity, or affected modules of any concrete code-brief drift.
• Whether Grok Bot is currently producing false positives, false negatives, or is operating correctly.
• Any runtime errors, test failures, or API regressions associated with the drift.

To confirm a specific root cause, the following evidence is needed: the actual Grok Bot finding comments on this issue (version-stamped), the diff between the flagged code and the corresponding brief, and any CI/test output associated with the affected version.

Resolution Steps

These steps apply to the general operational protocol, not to a specific version-stamped finding (which requires its own evidence).

1. Identify the relevant version stamp. Locate the most recent unresolved Grok Bot comment on this issue. Confirm the stamp format matches the expected pattern (e.g., v2393).

1. Retrieve the specific drift. For each finding, pull the exact diff between the flagged code path and the corresponding brief section cited by Grok Bot.

1. Determine the authoritative source of truth. Decide whether the brief or the code is correct for that version. This decision belongs to the human owner (Konyo), not to either bot.

1. Apply the fix in isolation. Claude applies a minimal, targeted fix scoped to the drifted logic only. Do not bundle unrelated changes into a drift-correction commit.

1. Do not reopen issue #4. Any findings that touch /api/board_tick must be handled in a new issue or documented within this issue under the appropriate version stamp. The closed issue #4 must remain closed.

1. Do not cross-post to issue #3. Backend code findings stay here. If a finding has a UI/brief presentation dimension, note the relationship in a comment on this issue only — do not duplicate to #3.

1. Mark findings resolved per stamp. After Claude ships a fix, reply to the specific Grok Bot comment with a resolution note referencing the commit SHA and the version stamp.

Verification

After Claude applies a fix for a given version stamp:

1. Confirm the diff resolves the cited drift:

git diff <BASE_COMMIT> <FIX_COMMIT> -- <AFFECTED_FILE_PATH>

Verify the changed lines directly address the brief section cited by Grok Bot.

2. Run the relevant test suite for the affected module:

# Replace with your actual test runner and path
npm test -- --testPathPattern=<AFFECTED_MODULE>
# or
pytest tests/<AFFECTED_MODULE>/

Expected: all tests pass; no new failures introduced.

3. Confirm Grok Bot does not re-flag the same finding on the next tree read. If the same finding reappears under a subsequent version stamp, the fix was incomplete or the brief drifted again after the fix.

4. Confirm issue #4 remains closed and that no new references to /api/board_tick have been added to this issue's comments without a corresponding new tracking issue.

Prevention

Enforce brief-to-code linkage at commit time:

• Add a CI check or pre-commit hook that requires a brief reference annotation (e.g., a comment or metadata tag) on any function or module that is specification-governed. Untagged changes to governed paths fail the check.

Gate merges on Grok Bot clearance:

• If the pipeline permits it, block PR merges on files with open Grok Bot findings for the current version stamp. Require explicit human sign-off before merge.

Isolate /api/board_tick permanently:

• Add a linter rule or CI check that fails if issue #4 is referenced in new comments, commit messages, or code annotations, reinforcing the closed boundary.

Separate brief queues by domain:

• Enforce queue routing at the bot level: Grok Bot should include a routing label (backend vs. briefs) in its output so that misdirected posts can be caught automatically before a human reads them.

Version-stamp audit on a fixed cadence:

• Run a periodic (e.g., weekly) audit that lists all version stamps in this issue with no associated resolution comment, flagging any that have aged beyond an agreed SLA (e.g., 5 business days unresolved).

Track drift frequency by module:

• Aggregate Grok Bot findings over time to identify which code paths drift most frequently. High-frequency drift in a module is a signal that its brief is ambiguous, its ownership is unclear, or its automated generation pipeline needs tighter constraints.