{"id":"ad202b88-163b-4342-b2dd-8c9ddf6b162e","shortId":"C9R4rA","kind":"skill","title":"ql-intent-check","tagline":"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","description":"# ql-intent-check — intent-drift audit\n\n## Purpose\n\nLong 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.\n\nAcademic backing:\n- **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.\n- **Agent Drift (arXiv:2601.04170)**: introduces Agent Stability Index (ASI) and shows all models drift under pressure.\n- **Goal Drift in LM Agents (arXiv:2505.02709)**: Claude 3.5 Sonnet holds goals for 100K tokens but drifts under competing objectives.\n\n`ql-intent-check` operationalizes a lean version of SCF's Drift Monitor for quantum-loop's pipeline.\n\n## Immutable intent snapshot\n\nThe first time `/ql-brainstorm` runs, it MUST store the user's verbatim first-message text at `quantum.json.userIntent`:\n\n```json\n{\n  \"userIntent\": {\n    \"text\": \"<verbatim first-message text from user>\",\n    \"timestamp\": \"<ISO 8601>\",\n    \"source_message_id\": \"<optional session ID>\"\n  }\n}\n```\n\nThis 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.\n\nIf `quantum.json.userIntent` is missing, this skill emits a WARNING and degrades to \"compare stage-to-stage\" mode (less precise but still useful).\n\n## Stages audited\n\n1. **Intent → Design**: `userIntent.text` vs `docs/plans/<date>-<topic>-design.md`.\n2. **Design → PRD**: design.md vs `tasks/prd-<feature>.md`.\n3. **PRD → Plan**: PRD vs `quantum.json.stories[].acceptanceCriteria`.\n4. **Plan → Implementation**: AC text vs commit messages + test names + code comments.\n5. **Implementation → Review**: commit content vs `ql-review` output.\n\nAt each stage, compute:\n- **Objects carried**: nouns / domain entities present in both sides (Jaccard over extracted noun-phrases).\n- **Verbs carried**: action phrases.\n- **Constraints carried**: numeric thresholds, time bounds, technology mandates, non-goals.\n- **Novelty introduced**: new objects/verbs/constraints present downstream but absent upstream.\n\n## Detection rules\n\n### Rule 1 — Objects dropped without justification\n\nAn 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.\n\n### Rule 2 — Constraints softened or dropped\n\nNumeric 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).\n\n### Rule 3 — Objects introduced without upstream source\n\nAn 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.\n\n### Rule 4 — Non-goals violated\n\nPRD §5 non-goals list vs actual commit files. If a commit touches a path explicitly marked non-goal, emit a **CRITICAL** finding.\n\n### Rule 5 — AC paraphrase mismatch\n\nEvery 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.\n\n### Rule 6 — Test coverage gap per AC\n\nEvery 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.\n\n### Rule 7 — Implementation scope creep\n\nCommit diffs touching files outside the PRD-declared `files_changed` whitelist. Two sub-cases:\n- Test files: OK by default.\n- Production files: **HIGH** finding unless the PRD ACs authorize it (grep AC text for the file path or a covering abstraction).\n\n## Input\n\n- `quantum.json` (must exist; `userIntent` field is preferred but optional).\n- Current branch state.\n- Optional: `--since-commit=<sha>` to scope to a recent window.\n\n## Output\n\nEmits JSON at `quantum.intentDrift[<feature-id>]`:\n\n```json\n{\n  \"timestamp\": \"<ISO 8601>\",\n  \"base_sha\": \"<first-commit>\",\n  \"head_sha\": \"<last-commit>\",\n  \"has_immutable_intent\": true,\n  \"stages_audited\": [\"intent→design\", \"design→prd\", \"prd→plan\", \"plan→impl\"],\n  \"findings\": [\n    {\n      \"id\": \"DRIFT-001\",\n      \"rule\": \"Rule 2 — Constraint softened\",\n      \"severity\": \"high\",\n      \"original\": \"must complete in under 100ms\",\n      \"source\": \"userIntent.text\",\n      \"downstream\": \"target 200ms\",\n      \"downstream_location\": \"tasks/prd-feature.md:44\",\n      \"clarification_id_if_any\": null,\n      \"suggested_action\": \"Either (a) add a userClarifications entry explaining the re-negotiation, or (b) tighten PRD AC to ≤100ms and re-plan.\"\n    }\n  ],\n  \"summary\": {\n    \"critical\": 0,\n    \"high\": 1,\n    \"medium\": 3,\n    \"low\": 0,\n    \"info\": 0\n  },\n  \"verdict\": \"DRIFT_DETECTED_REVIEW_REQUIRED\"\n}\n```\n\nVerdicts:\n- `NO_DRIFT` — zero findings.\n- `MINOR_DRIFT` — only low/info findings.\n- `DRIFT_DETECTED_REVIEW_REQUIRED` — any medium or higher.\n- `CRITICAL_DRIFT_BLOCKS_MERGE` — ≥1 critical.\n\n## Anti-rationalization guards\n\n| The agent says… | The truth is… |\n|-----------------|---------------|\n| \"The user's intent is implicit in the PRD\" | No. PRD is a paraphrase of the intent. Keep the verbatim intent separately and audit against it. |\n| \"Scope-creep is a feature, the user will appreciate it\" | Rule 3 explicitly requires user confirmation. Silently expanded scope is expanded review burden and possible rework. |\n| \"Non-goals are aspirational, violating them isn't critical\" | Non-goals are contracts. Violating them is a CRITICAL finding by Rule 4. |\n| \"AC paraphrase is fine, they mean the same thing\" | If they truly mean the same thing, the original should pass the AC. If they don't quite, the paraphrase hides a semantic slip. Rule 5 applies. |\n\n## How to invoke\n\n```\n/quantum-loop:ql-intent-check\n```\n\nOptional arguments:\n```\n/quantum-loop:ql-intent-check --feature=<prd-id>\n/quantum-loop:ql-intent-check --since-commit=<sha>\n/quantum-loop:ql-intent-check --fail-on=high    # exit non-zero if any high-or-above finding\n```\n\n## Integration with existing skills\n\n- **`ql-brainstorm`**: MUST write `quantum.json.userIntent` on first run (immutable). Schema extension below.\n- **`ql-spec`**: MUST preserve the PRD `§5 Non-goals` section verbatim.\n- **`ql-plan`**: MUST preserve AC text verbatim into `quantum.json.stories[].acceptanceCriteria`.\n- **`ql-execute`**: optionally runs this skill mid-pipeline (after every N merged stories) to detect drift early.\n- **`ql-deep-review`**: consumes the intent-drift signal as its risk-score input.\n\n## Required quantum.json schema extension\n\nPropose the following additive fields:\n\n```json\n{\n  \"userIntent\": {\n    \"text\": \"<verbatim>\",\n    \"timestamp\": \"<ISO 8601>\",\n    \"source_message_id\": \"<session ref>\"\n  },\n  \"userClarifications\": [\n    {\n      \"id\": \"CLAR-001\",\n      \"timestamp\": \"<ISO 8601>\",\n      \"text\": \"<verbatim>\",\n      \"re-negotiates\": [\"<intent sentence>\" or \"AC-3\"]\n    }\n  ],\n  \"intentDrift\": {\n    \"<feature-id>\": { /* output from this skill */ }\n  }\n}\n```\n\nThese additions are optional for existing quantum.json files (backward-compatible), but REQUIRED for new plans after this skill is in production.\n\n## Known limitations (honest)\n\n- **Lexical drift detection is shallow**. Advanced semantic-intent-graph extraction (per SCF 2604.16339) is Tier-B work, not shipped here.\n- **Verb extraction is heuristic**. English-centric; degrades on Chinese or mixed-language projects. Users with Chinese PRDs should treat findings as hints.\n- **Rule 7 scope-creep check** over-fires on refactoring commits. Consider `noqa`-style annotations on legitimate cross-cut commits.\n- **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.","tags":["intent","check","quantum","loop","andyzengmath","agent-skills","agentskills","claude-code","claude-code-plugin","claude-code-skill","skillsmp"],"capabilities":["skill","source-andyzengmath","skill-ql-intent-check","topic-agent-skills","topic-agentskills","topic-claude-code","topic-claude-code-plugin","topic-claude-code-skill","topic-skillsmp"],"categories":["quantum-loop"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/andyzengmath/quantum-loop/ql-intent-check","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add andyzengmath/quantum-loop","source_repo":"https://github.com/andyzengmath/quantum-loop","install_from":"skills.sh"}},"qualityScore":"0.461","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 22 github stars · SKILL.md body (8,448 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:05:28.434Z","embedding":null,"createdAt":"2026-04-24T01:02:06.529Z","updatedAt":"2026-05-18T19:05:28.434Z","lastSeenAt":"2026-05-18T19:05:28.434Z","tsv":"'-001':702,1056 '-1':1191 '-3':1064 '/2/3':1192 '/ql-brainstorm':195 '/quantum-loop':920,927,933,941 '0':756,762,764 '1':272,361,758,792 '100k':163 '100ms':438,715,749 '2':279,415,705 '20':82 '200ms':443,720 '2505.02709':156 '2601.04170':137 '2604.16339':109,1108 '3':286,460,760,842 '3.5':158 '4':293,499,880,1198 '44':724 '5':79,305,399,505,530,915,985,1204 '6':563 '7':605,1142 'absent':356 'abstract':650 'ac':27,93,296,440,531,540,568,570,589,637,641,747,881,902,996,1063,1205 'ac-n':539 'academ':102 'accept':537 'acceptance-criterion':536 'acceptancecriteria':292,553,1001 'action':336,731 'actual':511 'add':734 'addit':1044,1071 'advanc':1100 'agent':83,122,128,134,139,154,799 'also':592 'anchor':243 'annot':1156 'anti':795 'anti-ration':794 'app':1183 'appear':378,475,543 'append':234 'append-on':233 'appli':916 'appreci':839 'argument':926 'artifact':23,70,382 'arxiv':108,136,155 'asi':142 'aspir':861 'assumpt':1168 'audit':8,53,271,690,827 'author':638 'b':744,1112 'back':103 'backward':1079 'backward-compat':1078 'base':681 'block':790 'bound':343 'brainstorm':57,967 'branch':662 'brief':1178 'build':1179 'burden':853 'carri':320,335,339 'case':624,1196 'caus':118 'centric':1123 'chang':619 'check':4,49,173,387,924,931,937,945,1146 'chines':1126,1134 'clar':1055 'clarif':229,725 'claud':157 'code':303 'command':596 'comment':304 'commit':299,308,512,516,609,667,940,1152,1162 'compar':13,259 'compat':1080 'compet':168 'complet':435,712 'comput':318 'confirm':491,846 'consensus':105 'consid':1153 'constraint':100,338,416,424,458,706 'consum':1025 'content':309 'contract':871 'convent':603 'cover':649 'coverag':565 'creep':608,832,1145 'criterion':538 'critic':527,755,788,793,866,876 'cross':1160 'cross-cut':1159 'current':661 'cut':1161 'de':392,408 'de-scop':391,407 'declar':617 'deep':1023 'default':629 'degrad':257,1124 'design':274,280,692,693 'design.md':24,278,282 'detect':30,246,358,767,781,1018,1097,1193 'diff':610 'diverg':32,114 'docs/plans':277 'domain':322 'downstream':22,354,381,430,718,721 'drift':7,34,52,91,132,135,147,151,166,181,245,701,766,772,776,780,789,1019,1029,1096 'drop':363,386,419 'e.g':431 'earli':1020 'either':732 'emit':253,410,444,486,525,675 'english':1122 'english-centr':1121 'entiti':323 'entri':455,554,737 'everi':534,569,1013 'evid':38 'execut':60,1004 'exercis':582 'exist':654,963,1075 'exit':950 'expand':848,851 'expans':495 'explain':738 'explicit':390,449,520,581,843 'extens':976,1040 'extract':330,1105,1118 'fail':947 'fail-on':946 'failur':124 'featur':835,932 'feel':45 'field':218,656,1045 'file':36,513,578,612,618,626,631,645,1077 'find':413,447,489,528,561,587,633,699,774,779,877,960,1138 'fine':884 'fire':1149 'first':193,205,373,972,1175 'first-messag':204 'flag':33 'follow':1043 'forgotten':99 'formal':110 'format':77 'fragil':1170 'framework':106 'gap':566 'goal':98,150,161,348,402,502,508,524,859,869,988,1201 'graph':131,1104 'grep':640 'ground':241 'ground-truth':240 'guard':797 'hard':423 'head':683 'heurist':1120 'hide':910 'high':446,560,632,709,757,949,957 'high-or-abov':956 'higher':787 'hint':1140 'hold':160 'honest':1094 'id':216,700,726,1052,1054 'immut':19,189,220,686,974,1165 'immutable-int':1164 'impl':698 'implement':28,295,306,483,606 'implicit':809 'index':141 'info':763 'input':651,1036 'integr':961 'intent':3,6,18,48,51,89,113,130,172,190,273,427,497,687,691,807,820,824,923,930,936,944,1028,1103,1166 'intent-drift':5,50,1027 'intentdrift':1065 'introduc':138,350,462 'invent':484 'invoc':84 'invok':919 'isn':864 'jaccard':328 'json':210,676,679,1046 'justif':365 'keep':821 'known':1092 'languag':1130 'lean':176,1188 'least':575 'legitim':1158 'less':265 'lexic':548,555,1095 'limit':1093 'line':37 'list':394,405,509 'live':230,396 'lm':153 'locat':722 'long':55 'loop':12,186,601 'low':761 'low/info':778 'mandat':345 'map':572,585 'mark':521 'md':285 'mean':886,893 'medium':412,488,586,759,785 'merg':41,791,1015 'messag':206,215,300,374,1051,1176 'mid':1010 'mid-pipelin':1009 'minor':775 'mismatch':533,556 'miss':250,584 'mix':1129 'mixed-languag':1128 'mode':264 'model':146 'monitor':133,182 'multi':121 'multi-ag':120 'must':198,434,591,653,711,968,981,994 'n':541,1014 'name':111,302 'negoti':452,742,1061 'never':226 'new':351,1084 'non':97,347,401,501,507,523,858,868,952,987,1200 'non-goal':96,346,400,500,506,522,857,867,986,1199 'non-zero':951 'noqa':1154 'noun':321,332 'noun-phras':331 'novelti':349 'nowher':476 'null':729 'numer':340,420 'object':169,319,362,367,461,467 'objects/verbs/constraints':352 'often':478 'ok':627 'one':576 'operation':174 'option':660,664,925,1005,1073 'origin':17,88,710,898 'output':314,674,1066 'outsid':613 'over-fir':1147 'paraphras':62,532,817,882,909,1206 'pass':900 'path':519,646 'per':127,567,597,1106 'per-ag':126 'phrase':333,337 'pipelin':56,188,1011 'plan':59,288,294,696,697,753,993,1085 'possibl':855 'potenti':385 'prd':25,281,287,289,398,439,471,504,535,616,636,694,695,746,812,814,984 'prd-declar':615 'prds':1135 'precis':266 'prefer':658 'prescrib':125 'present':324,353,368,425,468 'preserv':982,995 'pressur':149 'product':630,1091 'project':1131 'propos':1041 'provid':1208 'purpos':54 'ql':2,47,171,312,922,929,935,943,966,979,992,1003,1022 'ql-brainstorm':965 'ql-deep-review':1021 'ql-execut':1002 'ql-intent-check':1,46,170,921,928,934,942 'ql-plan':991 'ql-review':311 'ql-spec':978 'quantum':11,185,600 'quantum-loop':10,184,599 'quantum.intentdrift':678 'quantum.json':26,473,652,1038,1076 'quantum.json.stories':291,552,1000 'quantum.json.userintent':209,248,970 'quit':907 'ration':796 're':66,451,741,752,1060 're-negoti':450,740,1059 're-plan':751 're-read':65 'read':67 'recent':672 'refactor':1151 'reinterpret':95 'requir':769,783,844,1037,1082 'review':61,307,313,768,782,852,1024 'rework':856 'rewrit':72,456 'risk':1034 'risk-scor':1033 'root':117 'rule':359,360,414,459,498,529,562,604,703,704,841,879,914,1141,1190,1197,1203 'run':196,973,1006 'say':433,441,800 'scf':107,179,1107 'schema':975,1039 'scope':393,409,485,494,607,669,831,849,1144 'scope-creep':830,1143 'scope-expans':493 'score':1035 'section':989 'semant':31,104,112,129,912,1102 'semantic-intent-graph':1101 'separ':825 'sever':708 'sha':682,684 'shallow':1099 'ship':1115 'show':144 'side':327 'sign':480 'signal':1030 'signific':92 'silent':94,847 'sinc':666,939 'since-commit':665,938 'skill':252,964,1008,1069,1088 'skill-ql-intent-check' 'slip':913 'snapshot':20,191,237,1167,1185 'soften':101,417,707 'sonnet':159 'sourc':214,465,716,1050 'source-andyzengmath' 'spec':44,58,980 'specifi':593 'stabil':140 'stage':64,80,261,263,270,317,689 'stage-to-stag':260 'state':663 'still':268,1207 'store':199 'stori':1016 'style':1155 'sub':623 'sub-cas':622 'subsequ':228 'suggest':730 'summari':754 'swe':123 'symbol':579 'target':442,719 'tasks/prd-':284 'tasks/prd-feature.md':723 'technolog':344 'test':301,564,577,625 'testfirst':602 'text':207,212,297,642,997,1048,1058 'thing':889,896 'threshold':341,421,559 'tier':1111 'tier-b':1110 'tighten':745 'time':194,342 'timestamp':213,680,1049,1057 'todo':1182 'token':164 'topic-agent-skills' 'topic-agentskills' 'topic-claude-code' 'topic-claude-code-plugin' 'topic-claude-code-skill' 'topic-skillsmp' 'touch':517,611 'treat':1137 'trivial':547 'true':688 'truli':892 'truth':242,802 'two':621 'unless':448,634 'updat':227 'upstream':69,357,464,477 'use':39,269 'user':15,86,201,371,432,490,805,837,845,1132,1173 'userclarif':232,454,736,1053 'userint':211,655,1047 'userintent.text':275,717 'valu':1209 'variat':549 'verb':334,1117 'verbatim':203,544,823,990,998 'verdict':765,770 'verif':595 'version':177 'violat':503,862,872 'vs':276,283,290,298,310,510 'warn':255 'weaken':429 'whether':492 'whitelist':620 'window':673 'without':364,463 'work':1113 'write':969 'written':223 'zero':773,953","prices":[{"id":"289bf661-d7d3-45ee-9b3e-87362b405f17","listingId":"ad202b88-163b-4342-b2dd-8c9ddf6b162e","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"andyzengmath","category":"quantum-loop","install_from":"skills.sh"},"createdAt":"2026-04-24T01:02:06.529Z"}],"sources":[{"listingId":"ad202b88-163b-4342-b2dd-8c9ddf6b162e","source":"github","sourceId":"andyzengmath/quantum-loop/ql-intent-check","sourceUrl":"https://github.com/andyzengmath/quantum-loop/tree/master/skills/ql-intent-check","isPrimary":false,"firstSeenAt":"2026-04-24T01:02:06.529Z","lastSeenAt":"2026-05-18T19:05:28.434Z"}],"details":{"listingId":"ad202b88-163b-4342-b2dd-8c9ddf6b162e","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"andyzengmath","slug":"ql-intent-check","github":{"repo":"andyzengmath/quantum-loop","stars":22,"topics":["agent-skills","agentskills","claude-code","claude-code-plugin","claude-code-skill","skillsmp"],"license":"mit","html_url":"https://github.com/andyzengmath/quantum-loop","pushed_at":"2026-05-03T18:23:03Z","description":"Spec-driven autonomous development loop for Claude Code. Combines structured PRD generation, dependency DAG execution, two-stage review gates, and Iron Law verification.","skill_md_sha":"197e5016e7768649aff124a2f2af3008cd2bfadf","skill_md_path":"skills/ql-intent-check/SKILL.md","default_branch":"master","skill_tree_url":"https://github.com/andyzengmath/quantum-loop/tree/master/skills/ql-intent-check"},"layout":"multi","source":"github","category":"quantum-loop","frontmatter":{"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.\""},"skills_sh_url":"https://skills.sh/andyzengmath/quantum-loop/ql-intent-check"},"updatedAt":"2026-05-18T19:05:28.434Z"}}