ql-intent-check

Name: ql-intent-check
Author: andyzengmath

23stars0forks

How to install ql-intent-check?

andyzengmath/quantum-loop/ql-intent-check

$npx -y skills add andyzengmath/quantum-loop --skill ql-intent-check

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# ql-intent-check — intent-drift audit
2
3	## Purpose
4
5	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.
6
7	Academic backing:
8	- 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.
9	- Agent Drift (arXiv:2601.04170): introduces Agent Stability Index (ASI) and shows all models drift under pressure.
10	- Goal Drift in LM Agents (arXiv:2505.02709): Claude 3.5 Sonnet holds goals for 100K tokens but drifts under competing objectives.
11
12	`ql-intent-check` operationalizes a lean version of SCF's Drift Monitor for quantum-loop's pipeline.
13
14	## Immutable intent snapshot
15
16	The first time `/ql-brainstorm` runs, it MUST store the user's verbatim first-message text at `quantum.json.userIntent`:
17
18	```json
19	{
20	"userIntent": {
21	"text": "<verbatim first-message text from user>",
22	"timestamp": "<ISO 8601>",
23	"source_message_id": "<optional session ID>"
24	}
25	}
26	```
27
28	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.
29
30	If `quantum.json.userIntent` is missing, this skill emits a WARNING and degrades to "compare stage-to-stage" mode (less precise but still useful).
31
32	## Stages audited
33
34	1. Intent → Design: `userIntent.text` vs `docs/plans/<date>-<topic>-design.md`.
35	2. Design → PRD: design.md vs `tasks/prd-<feature>.md`.
36	3. PRD → Plan: PRD vs `quantum.json.stories[].acceptanceCriteria`.
37	4. Plan → Implementation: AC text vs commit messages + test names + code comments.
38	5. Implementation → Review: commit content vs `ql-review` output.
39
40	At each stage, compute:
41	- Objects carried: nouns / domain entities present in both sides (Jaccard over extracted noun-phrases).
42	- Verbs carried: action phrases.
43	- Constraints carried: numeric thresholds, time bounds, technology mandates, non-goals.
44	- Novelty introduced: new objects/verbs/constraints present downstream but absent upstream.
45
46	## Detection rules
47
48	### Rule 1 — Objects dropped without justification
49
50	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.
51
52	### Rule 2 — Constraints softened or dropped
53
54	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).
55
56	### Rule 3 — Objects introduced without upstream source
57
58	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.
59
60	### Rule 4 — Non-goals violated
61
62	PRD §5 non-goals list vs actual commit files. If a commit touches a path explicitly marked non-goal, emit a CRITICAL finding.
63
64	### Rule 5 — AC paraphrase mismatch
65
66	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.
67
68	### Rule 6 — Test coverage gap per AC
69
70	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.
71
72	### Rule 7 — Implementation scope creep
73
74	Commit diffs touching files outside the PRD-declared `files_changed` whitelist. Two sub-cases:
75	- Test files: OK by default.
76	- Production files: HIGH finding unless the PRD ACs authorize it (grep AC text for the file path or a covering abstraction).
77
78	## Input
79
80	- `quantum.json` (must exist; `userIntent` field is preferred but optional).
81	- Current branch state.
82	- Optional: `--since-commit=<sha>` to scope to a recent window.
83
84	## Output
85
86	Emits JSON at `quantum.intentDrift[<feature-id>]`:
87
88	```json
89	{
90	"timestamp": "<ISO 8601>",
91	"base_sha": "<first-commit>",
92	"head_sha": "<last-commit>",
93	"has_immutable_inte

People who liked this also viewed

6 picks

Type

ql-intent-check

23stars0forks

View on GitHub

How to install ql-intent-check?

andyzengmath/quantum-loop/ql-intent-check

$npx -y skills add andyzengmath/quantum-loop --skill ql-intent-check

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# ql-intent-check — intent-drift audit
2
3	## Purpose
4
5	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.
6
7	Academic backing:
8	- 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.
9	- Agent Drift (arXiv:2601.04170): introduces Agent Stability Index (ASI) and shows all models drift under pressure.
10	- Goal Drift in LM Agents (arXiv:2505.02709): Claude 3.5 Sonnet holds goals for 100K tokens but drifts under competing objectives.
11
12	`ql-intent-check` operationalizes a lean version of SCF's Drift Monitor for quantum-loop's pipeline.
13
14	## Immutable intent snapshot
15
16	The first time `/ql-brainstorm` runs, it MUST store the user's verbatim first-message text at `quantum.json.userIntent`:
17
18	```json
19	{
20	"userIntent": {
21	"text": "<verbatim first-message text from user>",
22	"timestamp": "<ISO 8601>",
23	"source_message_id": "<optional session ID>"
24	}
25	}
26	```
27
28	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.
29
30	If `quantum.json.userIntent` is missing, this skill emits a WARNING and degrades to "compare stage-to-stage" mode (less precise but still useful).
31
32	## Stages audited
33
34	1. Intent → Design: `userIntent.text` vs `docs/plans/<date>-<topic>-design.md`.
35	2. Design → PRD: design.md vs `tasks/prd-<feature>.md`.
36	3. PRD → Plan: PRD vs `quantum.json.stories[].acceptanceCriteria`.
37	4. Plan → Implementation: AC text vs commit messages + test names + code comments.
38	5. Implementation → Review: commit content vs `ql-review` output.
39
40	At each stage, compute:
41	- Objects carried: nouns / domain entities present in both sides (Jaccard over extracted noun-phrases).
42	- Verbs carried: action phrases.
43	- Constraints carried: numeric thresholds, time bounds, technology mandates, non-goals.
44	- Novelty introduced: new objects/verbs/constraints present downstream but absent upstream.
45
46	## Detection rules
47
48	### Rule 1 — Objects dropped without justification
49
50	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.
51
52	### Rule 2 — Constraints softened or dropped
53
54	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).
55
56	### Rule 3 — Objects introduced without upstream source
57
58	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.
59
60	### Rule 4 — Non-goals violated
61
62	PRD §5 non-goals list vs actual commit files. If a commit touches a path explicitly marked non-goal, emit a CRITICAL finding.
63
64	### Rule 5 — AC paraphrase mismatch
65
66	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.
67
68	### Rule 6 — Test coverage gap per AC
69
70	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.
71
72	### Rule 7 — Implementation scope creep
73
74	Commit diffs touching files outside the PRD-declared `files_changed` whitelist. Two sub-cases:
75	- Test files: OK by default.
76	- Production files: HIGH finding unless the PRD ACs authorize it (grep AC text for the file path or a covering abstraction).
77
78	## Input
79
80	- `quantum.json` (must exist; `userIntent` field is preferred but optional).
81	- Current branch state.
82	- Optional: `--since-commit=<sha>` to scope to a recent window.
83
84	## Output
85
86	Emits JSON at `quantum.intentDrift[<feature-id>]`:
87
88	```json
89	{
90	"timestamp": "<ISO 8601>",
91	"base_sha": "<first-commit>",
92	"head_sha": "<last-commit>",
93	"has_immutable_inte

People who liked this also viewed

6 picks

Type