ql-intent-check

name: ql-intent-check description: Intent-drift audit for quantum-loop. Compares the user's original intent (immutable snapshot) against downstream artifacts (design.md → PRD → quantum.json ACs → implementation) to detect semantic divergence. Flags drift with file:line evidence. Use before merge or when specs feel "rewritten." allowed-tools: Read, Grep, Glob, Bash

ql-intent-check — intent-drift audit

Purpose

Long pipelines (brainstorm → spec → plan → execute → review) paraphrase. Each stage re-reads an upstream artifact and rewrites it in its own format. Over 5 stages and 20+ agent invocations, the user's original intent can drift significantly — ACs silently reinterpreted, non-goals forgotten, constraints softened.

Academic backing:

• Semantic Consensus Framework (SCF, arXiv:2604.16339): formally names "Semantic Intent Divergence" as the root cause of multi-agent SWE failures. Prescribes per-agent Semantic Intent Graph + Drift Monitor.
• Agent Drift (arXiv:2601.04170): introduces Agent Stability Index (ASI) and shows all models drift under pressure.
• Goal Drift in LM Agents (arXiv:2505.02709): Claude 3.5 Sonnet holds goals for 100K tokens but drifts under competing objectives.

ql-intent-check operationalizes a lean version of SCF's Drift Monitor for quantum-loop's pipeline.

Immutable intent snapshot

The first time /ql-brainstorm runs, it MUST store the user's verbatim first-message text at quantum.json.userIntent:

{
  "userIntent": {
    "text": "<verbatim first-message text from user>",
    "timestamp": "<ISO 8601>",
    "source_message_id": "<optional session ID>"
  }
}

This field is immutable — it is written once and never updated. Subsequent clarifications live in userClarifications[] (append-only). The snapshot is the ground-truth anchor for drift detection.

If quantum.json.userIntent is missing, this skill emits a WARNING and degrades to "compare stage-to-stage" mode (less precise but still useful).

Stages audited

1. Intent → Design: userIntent.text vs docs/plans/<date>-<topic>-design.md.
2. Design → PRD: design.md vs tasks/prd-<feature>.md.
3. PRD → Plan: PRD vs quantum.json.stories[].acceptanceCriteria.
4. Plan → Implementation: AC text vs commit messages + test names + code comments.
5. Implementation → Review: commit content vs ql-review output.

At each stage, compute:

• Objects carried: nouns / domain entities present in both sides (Jaccard over extracted noun-phrases).
• Verbs carried: action phrases.
• Constraints carried: numeric thresholds, time bounds, technology mandates, non-goals.
• Novelty introduced: new objects/verbs/constraints present downstream but absent upstream.

Detection rules

Rule 1 — Objects dropped without justification

An object present in the user's first message that does NOT appear in any downstream artifact is a potential drop. Check against an explicit "de-scoped" list (should live in PRD §5 Non-goals). If not listed as de-scoped, emit a MEDIUM finding.

Rule 2 — Constraints softened or dropped

Numeric thresholds or hard constraints present in intent but weakened downstream. E.g., user says "must complete in under 100ms"; PRD AC says "target 200ms". Emit a HIGH finding unless explicitly re-negotiated (a userClarifications[] entry rewrites the constraint).

Rule 3 — Objects introduced without upstream source

An object present in the PRD or quantum.json that appears nowhere upstream. Often the sign of an implementer inventing scope. Emit a MEDIUM finding; user confirms whether scope-expansion was intentional.

Rule 4 — Non-goals violated

PRD §5 non-goals list vs actual commit files. If a commit touches a path explicitly marked non-goal, emit a CRITICAL finding.

Rule 5 — AC paraphrase mismatch

Every PRD acceptance-criterion (AC-N) should appear verbatim (or with trivial lexical variation) in a quantum.json.stories[].acceptanceCriteria[] entry. Lexical mismatch above a threshold → HIGH finding.

Rule 6 — Test coverage gap per AC

Every AC should map to at least one test (file + symbol) that explicitly exercises it. Missing mapping → MEDIUM finding. The AC itself must also specify the verification command per the quantum-loop testFirst convention.

Rule 7 — Implementation scope creep

Commit diffs touching files outside the PRD-declared files_changed whitelist. Two sub-cases:

• Test files: OK by default.
• Production files: HIGH finding unless the PRD ACs authorize it (grep AC text for the file path or a covering abstraction).

Input

• quantum.json (must exist; userIntent field is preferred but optional).
• Current branch state.
• Optional: --since-commit=<sha> to scope to a recent window.

Output

Emits JSON at quantum.intentDrift[<feature-id>]:

{
  "timestamp": "<ISO 8601>",
  "base_sha": "<first-commit>",
  "head_sha": "<last-commit>",
  "has_immutable_intent": true,
  "stages_audited": ["intent→design", "design→prd", "prd→plan", "plan→impl"],
  "findings": [
    {
      "id": "DRIFT-001",
      "rule": "Rule 2 — Constraint softened",
      "severity": "high",
      "original": "must complete in under 100ms",
      "source": "userIntent.text",
      "downstream": "target 200ms",
      "downstream_location": "tasks/prd-feature.md:44",
      "clarification_id_if_any": null,
      "suggested_action": "Either (a) add a userClarifications entry explaining the re-negotiation, or (b) tighten PRD AC to ≤100ms and re-plan."
    }
  ],
  "summary": {
    "critical": 0,
    "high": 1,
    "medium": 3,
    "low": 0,
    "info": 0
  },
  "verdict": "DRIFT_DETECTED_REVIEW_REQUIRED"
}

Verdicts:

• NO_DRIFT — zero findings.
• MINOR_DRIFT — only low/info findings.
• DRIFT_DETECTED_REVIEW_REQUIRED — any medium or higher.
• CRITICAL_DRIFT_BLOCKS_MERGE — ≥1 critical.

Anti-rationalization guards

How to invoke

/quantum-loop:ql-intent-check

Optional arguments:

/quantum-loop:ql-intent-check --feature=<prd-id>
/quantum-loop:ql-intent-check --since-commit=<sha>
/quantum-loop:ql-intent-check --fail-on=high    # exit non-zero if any high-or-above finding

Integration with existing skills

• ql-brainstorm: MUST write quantum.json.userIntent on first run (immutable). Schema extension below.
• ql-spec: MUST preserve the PRD §5 Non-goals section verbatim.
• ql-plan: MUST preserve AC text verbatim into quantum.json.stories[].acceptanceCriteria.
• ql-execute: optionally runs this skill mid-pipeline (after every N merged stories) to detect drift early.
• ql-deep-review: consumes the intent-drift signal as its risk-score input.

Required quantum.json schema extension

Propose the following additive fields:

{
  "userIntent": {
    "text": "<verbatim>",
    "timestamp": "<ISO 8601>",
    "source_message_id": "<session ref>"
  },
  "userClarifications": [
    {
      "id": "CLAR-001",
      "timestamp": "<ISO 8601>",
      "text": "<verbatim>",
      "re-negotiates": ["<intent sentence>" or "AC-3"]
    }
  ],
  "intentDrift": {
    "<feature-id>": { /* output from this skill */ }
  }
}

These additions are optional for existing quantum.json files (backward-compatible), but REQUIRED for new plans after this skill is in production.

Known limitations (honest)

• Lexical drift detection is shallow. Advanced semantic-intent-graph extraction (per SCF 2604.16339) is Tier-B work, not shipped here.
• Verb extraction is heuristic. English-centric; degrades on Chinese or mixed-language projects. Users with Chinese PRDs should treat findings as hints.
• Rule 7 scope-creep check over-fires on refactoring commits. Consider noqa-style annotations on legitimate cross-cut commits.
• The immutable-intent snapshot assumption is fragile. If the user's first message is brief ("build me a todo app"), the snapshot is too lean for rule-1/2/3 detection. In those cases, Rule 4 (non-goals) and Rule 5 (AC paraphrase) still provide value.