logical-bug-finder

name	logical-bug-finder
description	Generalized template for diagnosing complex logical patterns and bugs in unstructured codebases or texts.

A Template for Diagnosing and Replicating Fixes for Fuzzy Bugs

This document provides a methodology for diagnosing a specific bug and then finding and fixing similar logical errors across a codebase. It is designed for "fuzzy" problems where the issue is not a simple keyword but a flawed pattern of logic that may be implemented in different ways across multiple files.

The Core Principle: Concepts, Not Keywords

The goal is to move from a specific bug instance to an abstract, reusable heuristic. Don't just think about the specific filenames or variables; think about the role they play. This allows you to identify the same logical mistake even when the implementation details are different.

---

The Methodology

The process can be broken down into four distinct phases.

Phase 1: Deconstruct the Initial Anomaly

Before searching for anything, deeply understand the initial problem.

1. Identify the Symptom: Note the exact error message or incorrect behavior. This is the observable what.
2. Isolate the Clue: Find the critical piece of information that hints at the why. Often, this is a contrastive observation (e.g., "this command works when run alone, but fails inside the script," or "this works on small files, but not large ones").
3. Formulate a Concrete Hypothesis: Combine the symptom and the clue to form a precise, testable explanation for the failure.
   • Bad: "The script has a bug."
   • Good: "The process fails because it generates a necessary resource in Location A, but a later step incorrectly tries to access it from Location B."

Phase 2: Generalize the Bug into a Reusable Heuristic

Abstract the specific details from your hypothesis into a generic, flawed pattern. This is the most critical step for turning a one-off fix into a systemic search.

1. Identify the Conceptual Roles: Assign generic roles to the specific entities involved.

   • SCRIPT_TMPDIR=$(mktemp -d) becomes -> "A process step that initializes a context (e.g., a temporary workspace, a config variable, a resource handle)."
   • ffmpeg becomes -> "A tool or function that operates within that context."
   • transforms.trf becomes -> "An intermediate artifact or resource."

2. Define the Flawed Pattern: Describe the bug using these abstract concepts. This is your heuristic.

   Heuristic Example: A process initializes a required context (e.g., creates a temporary directory, sets a configuration variable), but a subsequent step within that process fails to use this context, instead relying on an incorrect default or hard-coded state.

Phase 3: Structure the Search (Faceted Investigation)

With a clear heuristic, you can now search the codebase efficiently. Instead of manually reading every file, you pivot to a faceted search to find high-probability candidates.

1. Search for Components, Not the Bug: You cannot directly search for "a logical error." Instead, search for the key components (the conceptual roles) you defined in Phase 2.
2. First Facet (High-Signal Keywords): Start with the most concrete and unique component of your pattern. This is often the "context initialization" step (e.g., the mktemp command, a call to a create_config function). This first pass should dramatically narrow the number of relevant files.
3. Second Facet (Cross-Referencing): Now, search for the other key component, the "tool or function that operates within the context" (e.g., ffmpeg, process_data).
4. Find the Intersection: The files that appear in both search result lists are your highest-priority candidates for investigation. Files that only match one facet are lower priority but may still be worth a quick look.

Phase 4: Iterative Verification and Correction

Analyze the prioritized list of candidates to confirm the bug and apply the fix.

1. Verify the Flawed Pattern: For each candidate file, read the code and ask: "Does this code match the full heuristic?"
   • Does it initialize a context?
   • Does it later use a tool that should depend on that context?
   • Crucially, is there a failure to pass the context from the first step to the second?
2. Apply a Conceptual Fix: If the pattern is confirmed, apply the fix. The fix should also be conceptualized first.
   • Bad: "Add -result /tmp/file to the command."
   • Good: "Ensure the 'acting tool' receives the correct path/handle/variable that was generated by the 'context initialization' step."

---

Summary Workflow

By following this Analyze -> Generalize -> Search -> Verify workflow, you can transform a vague, fuzzy bug-finding mission into a structured and repeatable engineering task.

It can also be used for other domains, e.g. below:

---

A Diagnostic Template for Finding Systemic Errors in Texts

This document describes a method for identifying a specific flaw in a single text—logical, conceptual, stylistic, or formal—and then using that insight to locate and correct the same underlying error across an entire corpus. It is designed for fuzzy problems: cases where the issue is not a single forbidden word or rule violation, but a recurring failure of reasoning, perspective, or constraint management that manifests differently in different places.

Core Principle: Roles and Constraints, Not Surface Words

The objective is to move from a concrete instance of failure to an abstract, reusable heuristic. Do not fixate on particular characters, quotations, page numbers, or phrases. Instead, identify the roles elements play in the error and the constraints that are being violated. This makes it possible to detect the same mistake even when it wears different linguistic costumes.

---

The Method

The process consists of four phases. Each phase builds discipline into what would otherwise be vague editorial intuition.

Phase 1: Deconstruct the Initial Anomaly

Before scanning the corpus, understand the first anomaly with surgical precision.

Start by identifying the symptom: what exactly feels wrong, inconsistent, or implausible. This might be an anachronism, a contradiction, a sudden shift in tone, a claim that undermines earlier premises, or a stylistic move that breaks the text’s own rules.

Next, isolate the clue that explains why it is wrong. This is usually a contrastive observation: the text behaves one way under condition X and another way under condition Y. For example, a narrator who is careful and precise elsewhere suddenly becomes sloppy, or a concept that is rigorously defined early on is later used loosely.

Then formulate a concrete hypothesis that explains the failure. Avoid vague judgments.

Bad: “The author made a mistake.” Good: “The author allows a character constrained by a historical setting to use concepts that presuppose later technological or cultural developments, violating the story’s temporal framework.”

The hypothesis must be precise enough that it could, in principle, be falsified.

---

Phase 2: Abstract the Error into a Reusable Heuristic

This is the most important step. You now strip away local details and describe the error as a general pattern.

Begin by identifying abstract roles.

A named historical figure becomes “an agent bound to a specific temporal and cultural context.” A modern term becomes “a concept whose existence depends on later developments.” A paragraph of dialogue becomes “a site where an agent expresses internal models of the world.”

Once the roles are clear, define the flawed pattern in terms of violated constraints.

Heuristic example:

An agent operating under a defined contextual constraint (historical, epistemic, cultural, logical) expresses knowledge, language, or assumptions that presuppose conditions outside that constraint, without the text acknowledging or justifying the breach.

This heuristic is now independent of genre, author, or vocabulary. It can apply equally to historical fiction, philosophy, journalism, or academic prose.

---

Phase 3: Structure the Search (Faceted Investigation)

Armed with a clear heuristic, you can now search efficiently instead of rereading everything.

You cannot search directly for “conceptual inconsistency.” Instead, you search for the components of the pattern.

First, locate instances of the strongest constraint-bearing element. This might be all passages involving historically fixed characters, all sections governed by a formal definition, or all claims derived from a stated premise.

Second, within those locations, search for the second component: expressions that could plausibly violate the constraint. These might include certain types of terminology, argumentative moves, metaphors, or assumptions.

Then intersect the results. The passages that satisfy both conditions are your highest-probability candidates. Items that match only one facet are lower priority, though still worth occasional inspection.

This is triage, not brute force.

---

Phase 4: Verification and Correction

Now you evaluate candidates one by one.

For each passage, ask whether it truly instantiates the heuristic.

Is the relevant constraint present? Does the passage introduce an element that depends on violating that constraint? Crucially, is the violation unacknowledged or unjustified, rather than deliberate (irony, satire, speculative framing)?

Only when the full pattern is present do you proceed to correction.

Corrections should be conceptual, not cosmetic.

Bad: “Replace the modern word with an older synonym.” Good: “Revise the passage so the agent’s language and assumptions remain consistent with the epistemic resources available within the defined context, or explicitly mark the deviation as intentional.”

The goal is not to patch a sentence, but to restore coherence to the system that produced it.

---

Summary Workflow

By following the sequence Analyze → Abstract → Search → Verify, you convert a vague sense that “something is off” into a disciplined analytical process. The method scales from a single essay to an entire library and trains both humans and machines to reason in terms of constraints, roles, and systemic patterns rather than isolated errors.

This is how local fixes become global understanding—and how intuition gets upgraded into method.