Demand Source Analysis Reference

July 27, 2026 · View on GitHub

Use this before loop-discovery.md when the input is a raw demand source, session signal, report row, repository entropy hint, or repeated-work suspicion. This reference turns loose demand into a bounded evidence pack. It does not choose the durable owner, create a Skill, wire automation, mine broad sessions, or render report output.

Core Rule

Demand is not a loop. A source becomes a loop candidate only after the agent can name the target, scope, repeated or costly intent, observed/configured boundary, existing coverage, stable input, missing proof, and risk boundary.

Use needs more evidence when the source cannot be reduced to one candidate demand. Do not promote from file age, line count, churn, keyword hits, global counters, loaded Skill text, static asset presence, or a single vague complaint.

Triage Workflow

Pin the target: name the repository, path, report row, workflow, issue, PR, session set, external object, or user-provided artifact.
Bound the source window: name the dates, session limit, report run, commit range, CI window, or user-provided note set. If there is no bound, say so and lower confidence.
Classify source families using the table below. Use mixed only after naming the primary source and the supporting source.
Separate evidence layers:
- configured presence: files, settings, Skills, hooks, commands, CI, specs
- observed behavior: session events, command output, reports, CI/review records, opened external data
- local entropy: drift, pressure, or missing validation that may explain repeated work
- user intent: explicit request, correction, priority, or acceptance signal
Collapse duplicates: merge variants only when the same trigger, input, procedure, output, and validation would handle them.
Check existing coverage before calling the demand uncovered. Observed Skill, hook, script, command, CI, or automation use usually means the next question is extension, repair, validation, or scheduling, not creation.
Rate demand strength with the ladder below.
Write the evidence pack and hand it to loop-discovery.md, or stop with needs more evidence and the exact missing proof.

Source Families

Source	Strong signal	Check before promotion	Evidence refs
User repetition	Similar asks, corrections, follow-ups, or explicit "do this every time" language recur	Is the repeated ask the same workflow, or only the same topic?	prompt ids, provided notes, issue text, review comments
Costly single demand	One setup, release, migration, security, or review task is expensive or high-risk enough to recur	Is future recurrence likely and bounded, or just speculative?	user statement, incident note, release checklist, risk record
Session behavior	`actionCandidates`, `planningSignals`, active long sessions, repeated validation gaps, observed hook/tool failures, or repeated repair loops	Are sessions workspace-scoped and active, not wall-span-only or global noise?	`sources`, `facets`, `insights`, bounded `show` samples
Report rows	Repeated findings, low-readiness patterns, schedule handoffs, missing validation, or repeated owner gaps appear in artifacts	Is the report row evidence-backed, or a projection/caveat?	report path, finding id, source JSON, quality check
Repo-local entropy	Documentation drift, dependency drift, code shape pressure, validation entropy, guardrail drift, or sensitive-boundary drift clusters around a target	Is it a confirmed defect, or only maintenance pressure?	files, commands, diffs, scan output, validator output
Existing coverage friction	A Skill, hook, script, command, rule, CI job, or automation exists but agents repeatedly repair, reconfigure, explain, or bypass it	Is the surface observed in use, and what manual step remains?	asset path, invocation evidence, failure logs, repair diffs
External workflow	CI, review, issue, PR, tracker, deployment, incident, or MCP-backed evidence repeats around the same target	Was the external record actually opened or provided?	opened records, copied logs, CI output, review ids
Strategic demand	The user names a recurring maintenance, triage, onboarding, review, monitoring, or governance need	Does the user also provide a stable input, cadence, target, or acceptance signal?	explicit user statement plus proposed stable input

Demand Strength Ladder

Use one of these labels in the evidence pack:

Observed repeated: two or more bounded observations share trigger, input, procedure, output, and validation shape.
Costly/high-risk: one observed demand is expensive, sensitive, release critical, or likely to recur because the same target will be revisited.
Covered but manual: an owner exists, but evidence shows repeated setup, repair, validation, context collection, handoff, or scheduling work.
Entropy-backed candidate: local drift or pressure suggests recurrence, but observed repetition is missing or weak.
Weak: one-off, broad, topic-only, sampled too narrowly, or missing stable input.
Unknown: source boundary is unavailable, external evidence was not opened, or the target cannot be named.

Only the first three normally proceed to owner selection. Entropy-backed candidate can proceed only when the missing proof is small and named. Weak and Unknown stop with needs more evidence.

Coverage Matrix

Before recommending any new durable surface, inspect enough coverage to avoid a duplicate:

Coverage surface	Counts as coverage when	Common next action
Skill	The Skill exists and observed use covers the workflow	Extend instructions, validation, examples, or schedule handoff
Hook / rule	A lifecycle point can warn, block, log, or enforce the check	Tune deterministic guardrail, not a Skill
Script / command	A repeatable extraction, check, transform, or shortcut already exists	Improve script output, docs, or invocation path
Automation / schedule	A stable cadence or event already runs or is approved	Add triage, state, stop, or validation evidence
Custom agent / subagent	Specialist role isolation or maker/checker split is already used	Tighten role prompt or review checklist
MCP / connector	External access exists and the missing part is workflow judgment	Keep MCP as access; route workflow owner separately
CI / external policy	Checks run on protected events or review gates	Fix check coverage or reporting, not agent memory
Docs / specs / rules	The durable decision exists but agents miss or reinterpret it	Improve routing, trigger wording, or reference placement

If coverage is configured but not observed, keep it as presence evidence. If coverage is observed but incomplete, name the manual residue instead of saying "no coverage."

False Positive Patterns

Do not promote these directly:

A popular file, large file, old file, or high-churn file without repeated demand or validation pain.
Multiple prompts about the same area that require different triggers, procedures, or outputs.
A loaded Skill, config file, hook setting, or plugin cache entry with no observed use.
Wall-span-only long sessions, idle/resume artifacts, or sampled sessions treated as representative without proof.
A report recommendation that lacks source JSON, finding id, validation command, or acceptance boundary.
A global user-home pattern applied to the current workspace without matching workspace evidence.
A sensitive or destructive workflow without a human gate, approval point, and risk boundary.
A request to "make it proactive" without trigger, input, verification, state, and stop condition.

Evidence Pack

Build the smallest pack that lets loop-discovery.md run its decision gate:

Target: repository, path, report, workflow, issue, PR, session set, or external object.
Scope/window: date range, session limit, report run, commit range, CI window, or user-provided note set.
Candidate demand: one sentence naming the repeated or costly work.
Primary source family: one of the source families above.
Supporting source family: optional second source, or none.
Evidence refs: exact files, commands, session ids, report rows, issue/PR ids, scan output, CI output, or user-provided notes.
Observed/configured boundary: what actually happened versus what is only configured, present, inferred, or sampled.
Demand strength: observed repeated, costly/high-risk, covered but manual, entropy-backed candidate, weak, or unknown.
Existing coverage: Skills, hooks, scripts, commands, rules, agents, MCP, automation, CI, specs, docs, or plugins already covering the work.
Manual residue: repeated setup, repair, validation, handoff, triage, context collection, approval, or scheduling that remains outside coverage.
Stable input: the repeatable evidence or event a future run can start from.
Risk boundary: files, credentials, external systems, approvals, or broad changes that need a human gate.
Missing proof: the exact evidence needed before a durable owner can be selected.

Do not include raw transcript dumps, secrets, credentials, private prompts, large logs, or global home activity that is not tied to the target workspace.

Handoff Criteria

Continue to loop-discovery.md when demand strength is observed repeated, costly/high-risk, covered but manual, or a narrowly bounded entropy-backed candidate.
Continue to ../agent-customize/skill-discovery.md only after Loop Discovery selects Create Skill or Extend Skill.
Continue to automation-readiness.md only after Loop Discovery selects automation, schedule-ready, or scheduled/background follow-up.
Continue to loop-state-ledger.md when the candidate may pause, resume, recur, run in the background, or compare results across runs.
Stop with needs more evidence when stable input, observed recurrence, verification, stop condition, coverage boundary, or safety boundary is missing.

Output

### Demand source analysis
- **Target**: ...
- **Scope/window**: ...
- **Candidate demand**: ...
- **Primary source family**: ...
- **Supporting source family**: ...
- **Evidence refs**: ...
- **Observed/configured boundary**: ...
- **Demand strength**: observed repeated | costly/high-risk | covered but manual | entropy-backed candidate | weak | unknown
- **Existing coverage**: ...
- **Manual residue**: ...
- **Stable input**: ...
- **Risk boundary**: ...
- **Missing proof**: ...
- **Next gate**: loop-discovery.md | needs more evidence

Keep the output compact enough that Loop Discovery can consume it as an evidence pack. Do not turn it into a second Loop Discovery report.