The Field Findings & Bugs Protocol v2 governs how an LLM captures, holds, compares, and promotes findings and bugs during live review or analytical work. It is not a patch spec, not a task plan, and not a summary style guide. Its job is to prevent weak findings, weak bug records, premature clustering, false generalization, and convergence by momentum — the pattern where an AI starts from the first salient point and builds structure around it before the rest of the field is open.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/XxYouDeaDPunKxX/ai-protocol-kit/llms.txt
Use this file to discover all available pages before exploring further.
Core Distinction: Registration ≠ Promotion
A finding or bug may be recorded early. It may not be generalized, clustered, elevated, or used to drive action until its relation to the wider field is sufficiently clear. This distinction is the foundation of the entire protocol. Registration is a low-threshold act — it preserves a local observation. Promotion is a high-threshold act — it authorizes action, clustering, rule extraction, or structural conclusion. The two are never collapsed into one step.A findings file is a disciplined holding field for live analytical pressure. It is not a patch queue, not a design doctrine, and not a summary of what already feels true.
Operating Posture
Do not start from the first salient point and build structure immediately. Open the field horizontally first. Keep the active lenses live at the same time. If they pull in opposite directions, treat that tension as information. Do not converge until the problem is closed enough to resolve that tension or bound it explicitly.Active Lenses
All eight lenses operate simultaneously during review. If they produce tension, that tension is preserved — not resolved by averaging or ignoring the minority signal.| Lens | What It Does |
|---|---|
| Mechanism beats heuristic | Prefer an explanation of how something breaks over a pattern-matched label |
| Privative but convergent | Identify what is absent or missing; converge only when the field is sufficiently complete |
| Miller constraint | Keep the active working set bounded; do not expand scope without naming it |
| Fail-closed on meaningful ambiguity | If an ambiguity materially changes what should happen next, keep the finding open — do not smooth over it |
| No formalization from single instance | A single finding may stand as a local case; it may not become a rule, family, or pattern by itself |
| Simplicity before meta-machinery | Do not introduce structural complexity to organize findings that could remain flat |
| The task is a point, the system is the volume | Any local finding exists inside a larger system; do not treat the surface as the whole |
| Local surface != local consequence | A finding on a visible surface may have consequences far from where it appears |
Protocol Rules
Close the object before capture
Before recording a finding, identify the target object, the active surface, the current scope, and the authority frame. If these are not closed enough, record the uncertainty before recording the finding itself.
Registration threshold
A finding may be registered when all three of the following are true:
- It has a surface that can be pointed to
- It is at least partly verifiable in the live object or live evidence base
- It can stand as a local point without pretending that wider relations are already known
Epistemic labeling is mandatory
Every finding must explicitly separate its epistemic state. Do not write inferred or hypothetical states as if they were verified.
| State | Definition |
|---|---|
| Verified | Directly observed in the live object or evidence base; can be pointed to without inference |
| Inferred | Reasoned from observable evidence; the reasoning chain is explicit and bounded |
| Hypothetical | Plausible given available evidence but not yet grounded in direct observation or closed inference |
Registration does not authorize promotion
Recording a finding does not yet authorize any of the following: clustering, generalization, rule extraction, sprint selection, patch recommendation, or structural conclusion.
Horizontal pass before promotion
Before promoting any finding, reopen the field horizontally. Check for relations, tensions, dependencies, exclusions, collisions, false groupings, and hidden asymmetries. Do not promote from an isolated point if its wider relation is still unknown and could change its meaning.
No formalization from single instance
A single finding may stand as a local case. It may not become a family, a rule, a pattern, or a strategy by itself unless the reason for promotion is explicitly justified.
Impact classification
Every finding must state whether its consequence currently appears: local / bounded; corridor-level / wider than local surface; or not yet closed.
Relevance threshold
A finding should not be kept alive merely because it sounds plausible or elegant. It must have at least one of: an operational consequence; a structural consequence; or an unresolved tension that could change a decision, patch, or recommendation.
Fail-closed capture
If a finding depends on an ambiguity that materially changes what should happen next, do not smooth over it. Mark the ambiguity and keep the finding open.
Promotion threshold
A finding may be promoted only when at least one of the following is true: it invalidates other findings; it orders other findings; it opens or closes a corridor; it changes the expected action; or it changes the recommendation boundary.
Compression rule
Do not multiply findings that collapse into the same governing issue. Fuse vertically only after the relation is clear. Until then, keep them separate and honestly bounded.
Operational States
Every finding in the holding field carries one of four states at any time.| State | When to Use It |
|---|---|
| Open | Registered, not yet fully bounded or ready for promotion review |
| Bounded | Relations, impact, and limits are clear; standing as a local point without wider claims |
| Deferred | Acknowledged, not currently actionable, explicitly parked |
| Closed | Resolved, promoted, invalidated, or confirmed out of scope |
Recommended Record Shape
Every registered finding should close the following fields:Failure Conditions
This protocol is designed to prevent a specific set of failure modes. When any of the following appears, the protocol has been violated.Registering vibes as findings
A finding that has no surface, cannot be pointed to, and is not partly verifiable does not meet the registration threshold. It is an impression, not a finding.
Treating inferred states as verified
Epistemic labeling is mandatory. Writing “the system does X” when the actual state is “the system appears to do X based on Y” collapses the distinction the protocol exists to protect.
Clustering too early
Grouping findings before their relations are clear produces false families. Two findings that appear related may belong to different governing issues — or may be in direct tension.
Promoting single cases into rules
One instance of a pattern is a local case. It is not a rule, a family, or a strategy. Promotion from a single instance requires explicit justification.
Widening scope without naming it
If the review scope expands during analysis, that expansion must be named. Silent scope expansion is a form of converging from momentum.
Converging from momentum
Building structure around the first salient finding before the field is open is convergence from momentum, not from evidence. The horizontal pass is not optional.
Turning findings into a patch plan
A findings file becomes a patch queue when promotion decisions are made before the promotion threshold is met. The file holds findings — it does not make decisions.
Turning findings into ideology
When a cluster of findings begins to confirm a pre-existing view rather than update it, the file has stopped functioning as a holding field and started functioning as a justification engine.
Practical Example: Reviewing a Repository for Publication Issues
Say you are reviewing a repository before making it public and you find a file that contains what appears to be a hardcoded API key.- Correctly labeled finding
- Premature generalization
ID: F-001
Surface:
Verified: A string matching the pattern of a third-party service API key is present in the file.
Inferred: The key is likely live — the service name matches a dependency in
Hypothetical: The key may be rotated or already expired. Unknown without checking the service dashboard.
Impact: Not yet closed — if the key is live and the repository goes public, the key is exposed. If it is already expired or a placeholder, there is no active risk.
Boundaries: Finding is local to this file and this key. No other credentials have been reviewed yet.
Relations: None established yet — horizontal pass not yet run.
Operational state: Open
Next review need: Verify whether the key is live before determining impact classification.This finding is correctly bounded. It makes no claim about whether other files have similar issues, whether this is a pattern, or whether the repository should be blocked from publication. It holds the evidence without promoting it.
Surface:
config/settings.py, line 42Verified: A string matching the pattern of a third-party service API key is present in the file.
Inferred: The key is likely live — the service name matches a dependency in
requirements.txt and the variable name is API_KEY not EXAMPLE_API_KEY.Hypothetical: The key may be rotated or already expired. Unknown without checking the service dashboard.
Impact: Not yet closed — if the key is live and the repository goes public, the key is exposed. If it is already expired or a placeholder, there is no active risk.
Boundaries: Finding is local to this file and this key. No other credentials have been reviewed yet.
Relations: None established yet — horizontal pass not yet run.
Operational state: Open
Next review need: Verify whether the key is live before determining impact classification.This finding is correctly bounded. It makes no claim about whether other files have similar issues, whether this is a pattern, or whether the repository should be blocked from publication. It holds the evidence without promoting it.