Investigating one area

Work through the following sequence for each selected area. Finish its evidence note and candidate decisions, then pass its coverage gate before starting the next area. When a hypothesis fails, consider other promising corrections in that area's related history instead of concluding that the whole area has no useful lesson.

1. Follow related history into discussions

Query GitHub commit history for the relevant file or directory at the evidence revision without the discovery seed's start-date filter, then identify the associated PRs. A shallow local git log cannot establish that no related history exists. For a new file, follow its parent subsystem, predecessor or renamed implementation.

Use that history to select related changes that could explain recurrence, clarify a correction or contradict a tentative lesson. Open the promising related PRs and actually read their relevant discussions, including older ones; a list of historical commits or PR titles does not complete this step. If no related change addresses the question, record the history examined and why it is irrelevant. Prefer recent evidence when equally informative, but retain older evidence that explains a still-current decision.

Save complete changed-path inventories for PRs used in the investigation and reconcile their counts against changedFiles from gh pr view or changed_files from REST pull metadata. gh pr view files can silently stop at 100; use the paginated files API when counts differ. Follow relevant GraphQL file, thread and comment cursors using pageInfo. The first 100 items does not prove exhaustion.

Compact feedback inventories may show IDs, paths, authors, replies and substantive excerpts without repeated review boilerplate. They help choose discussions; they are not full-thread examination.

2. Verify each correction independently

Read a selected root and all replies completely, preserving URLs, IDs, authors, dates, paths and relationships. Read the actual correction hunks, not just a downloaded diff. Connect each confirmed change to the feedback it addressed.

Distinguish a mistake found in a proposed revision from a defect merged, deployed or observed at runtime. A correction made before merge did not ship. A static warning or accepted formatting change does not prove an SSR mismatch occurred; establish render reachability before claiming that impact. Describe unproven runtime effects as risks, and do not infer what an agent knew or read from review feedback alone.

Check the latest replies and implementation. Merge, approval, resolution, reviewer disposition or an author's promise alone does not prove acceptance or a working correction. If later replies still identify the defect, do not call that defect corrected. An area or PR can contain both accepted and unresolved advice: assess each separately, retaining the confirmed part rather than accepting or rejecting the whole package.

A declined disposition records that advice was declined; it does not establish reviewer endorsement or technical correctness. Record who declined it, their reasoning and any unresolved concern. A guidance mismatch can still justify a finding when the stated decision and current implementation independently support it; do not repeat the declined advice as a proposed fix.

One clear acknowledged correction can support a reusable improvement when a specific context or Tessl verifier gap remains; related independent cases strengthen it. Repeated review passes on one PR remain one case, and one case does not establish recurrence. A historical fix alone is not a new finding: establish why the prevention or detection gap is still relevant. Do not reject a candidate solely because the example code was fixed.

3. Check current implementation, context and Tessl verifiers

Use the evidence revision. Read the corresponding current implementation; if a historical fix moved to a shared helper, trace that helper instead of describing the old patch as current code. Verify that feature-branch changes are present before calling them current behavior.

Read the relevant project entry guidance, inherited rules, skills and linked material, including the proposed target when a context update is plausible. For generated or installed .tessl/RULES.md, read the applicable manifests at the evidence revision. Tessl declarations are under tessl.json.dependencies, for example "tile-name": {"source": "file:relative/path"}. Resolve file sources relative to the manifest and read relevant declared rule/skill files. Listing dependency names or sources is not reading their guidance; nonexistent tiles/plugins fields do not mean no dependencies. A missing generated file does not mean its rules are absent. Record unresolved published guidance as an incomplete check.

Identify what existing guidance already says and which decision, if any, it leaves unclear or hard to discover. Existing documentation may need a justified entry point; acknowledge it and explain why placement matters. Existing guidance is not proof that a verifier covers the property, and an absent verifier is not proof that guidance needs editing. Record both checks independently.

Discover the relevant Tessl verifier declarations from root and scoped tessl.json manifests at the evidence revision. Resolve their configured paths and patterns, then read the applicable verifier definitions, applicability predicates, content filters, scope and checklist criteria. Follow the repository's declared Tessl Verify documentation when the schema or matching behavior is unclear; do not guess configuration keys. Read only declarations and definitions relevant to this area. A manifest listing or file name alone does not complete applicableVerifiers.

A supported negative result completes applicableVerifiers when either examined declarations show why none apply, or an inspected repository tree and relevant root, ancestor and scoped locations establish that no applicable tessl.json manifests or verifier declarations exist at the evidence revision. Record the revision, locations inspected, queries or tree reads and the absence established in the area note and check evidence. A manifest without verifier declarations is also a supported negative result after its relevant dependencies are checked for verifier configuration. Missing generated or installed files, failed reads, unresolved dependencies or incomplete discovery do not establish absence; record those as incomplete checks or concrete access blockers. Repositories without Tessl configuration remain valid targets for context-only, verifier-only or paired recommendations.

Check whether an existing verifier already expresses the proposed invariant and whether its configured scope includes the affected changes. Where relevant PR check results or logs are available, inspect them before claiming a verifier ran, missed the issue or detected it late. Configuration does not prove execution. Missing execution evidence limits that claim; it does not establish a missing verifier. A confirmed scope gap may justify tuning an existing verifier instead of adding another.

4. Decide and record the candidate

Choose the smallest justified remedy for the examined failure: context only, verifier only or paired. These are alternatives, not a quota. Explain why the selected remedy fits and why the other is unnecessary or unsupported. Separate facts, interpretation, counterevidence and uncertainty. Do not infer the contributor was an agent or claim a missing safeguard caused the defect without evidence.

Before ruling out a verifier, write down the narrowest observable invariant that would catch the examined mistake and assess it against the actual supported scopes. A file judge sees one file's current contents; a paths judge sees paths without contents; a diff judge sees patches without full file contents. Do not propose a combined diff-plus-full-source scope or assume a judge can retrieve other files. Identify where the required evidence lives, whether the chosen scope exposes it, what existing verifier covers it and any evidenced exceptions. Record this assessment in the candidate note, including for rejected candidates. Adequate guidance closes a context gap, not necessarily a detection gap; conversely, a rule being checkable does not establish that a new verifier is useful.

A broad rule requiring cross-file or runtime knowledge may have a narrower useful check within one file. For example, when a Contents lookup and follow-up blob read are visible in the same file, a verifier can check that a shared absence handler does not convert a failed blob read into a missing-file result. Evaluate that local invariant before dismissing the whole lesson as requiring caller knowledge. If verification remains unsupported, name the unavailable evidence or justified limitation rather than saying the rule is contextual or has exceptions. A single confirmed correction, or a mistake caught before merge, can still justify earlier detection when the invariant is reusable and a current detection gap remains. Do not reject it solely because Code Review caught it, the example was fixed or recurrence is unproven; evaluate the value and likely noise of the proposed check. Do not force a verifier or pair merely because a narrow check is possible.

For a context-only candidate, establish the specific missing, ambiguous or poorly exposed guidance. Give exact proposed wording, target file, placement and scope. Explain the decision it helps an agent make. Do not add guidance that merely repeats an existing, accessible rule. Verify every named helper, export, option, path and owner against current code. Preserve the scope and legitimate exceptions established by evidence in the wording itself: an SSR-only rule must not become a blanket ban on client-only rendering or event handlers. Proposed wording must be usable without changing application code first: do not document a private helper as an available export or prescribe a new shared API, refactor or ownership move as if it already exists. If implementation work is a prerequisite, keep that hypothesis in notes and retain only an independently useful context update supported by current behavior.

For a verifier-only candidate, establish the specific uncovered or incorrectly scoped property despite adequate context. Propose a concrete Tessl verifier or a precise amendment to an existing one: name, target paths, applicability predicate, one supported scope (file, paths or diff), binary pass/fail criteria and legitimate exceptions. State what evidence the judge needs and whether that evidence is available within the proposed scope. Ground applicability, scope and exceptions in examined code, guidance or discussions. Do not broaden an invoice lesson into all billing records, invent exempt route classes or add adjacent accessibility rules without supporting evidence. If a helper or wrapper needs examination outside the proposed scope, name that dependency and mark the criterion incomplete until the evidence is available. A vague suggestion to add verification is not a candidate. Read at least one relevant violating example and its corrected or compliant counterpart within the proposed judge scope; record the expected verdict and the exact evidence that makes each decidable. Inspect filters and exceptions for whether they would skip the violation or reject the correction. This is a readiness assessment, not a claim of running the verifier: separate expected verdicts from actual backtest results, and name any remaining tuning needed before enforcement.

For shell-related candidates, establish whether the instructions actually direct inserting external text into shell source. A quoted placeholder is evidence of risky guidance, not proof of unsafe execution or an observed exploit. Text is not trusted merely because it arrived through a run input, a CLI result, a title or a branch name; justify exceptions with examined validation or a construction that keeps values as opaque arguments. Where provenance is not visible to the judge, record not applicable rather than asserting safety.

For a paired candidate, identify one shared failure and two distinct gaps: the context explains the decision to make, while the verifier checks an observable property of the resulting change. Supply the concrete context update and verifier specification above, with matching scope and exceptions. Do not force an explanatory context update when the rule is already clear, or invent a verifier when the lesson cannot be checked reliably.

Reject refuted, declined, superseded or already adequately covered advice. Inspect the relevant guidance and verifiers before declaring a gap in either. A documented behavior does not justify another context bullet by itself, nor does it justify rejecting a verifier-only candidate without assessing the detection gap. Read implementation and tests as evidence when useful, but do not expand the recommendation into standalone unit-test, CI or application-code work.

Before retaining a candidate, check that its title and analysis describe the current guidance or detection gap, rather than presenting a repaired historical defect as a current bug. Reconcile causal, temporal and runtime claims with the examined evidence. Then reread its recommendation as an implementer: can the context be followed with current APIs, can the verifier decide its criteria from the stated scope, and are limitations or prerequisite work explicit? Distinguish an applicability signal from a complete definition: loader prefetch is one way data reaches an SSR render, and its absence does not prove output is client-only. Exemptions need positive evidence of the relevant boundary, such as an after-mount guard or event-only execution, not merely absence of one signal. Likewise, name the detector observed in the evidence without calling it the only detector when other execution results are unavailable. A pair must survive this check independently for both components. Narrow or reject unsupported parts instead of publishing an attractive but unusable pair.

Save a concise area note: question and paths; history queries and related PRs; full thread IDs with brief correction/author-response passages; actual correction hunks; current implementation, guidance and relevant verifiers read; remedy choice, candidate decisions and verified gaps. A list of IDs or assertion that guidance is absent is insufficient. Keep incomplete hypotheses in notes, outside deliverable proposals. Missing checks that could reverse a recommendation block publication.

Then investigate the next area. If evidence is too thin, widen related history or choose another promising area. If access or rate limits block completion, report the concrete missing checks. A zero-finding result needs examined evidence and guidance supporting the decisions, not an assumption that every rule is already covered.

GitHub history lookups

For the area-history step, adapt these read-only queries to the selected paths. Choose relevant commits and follow their associated PRs into discussions:

gh api --method GET repos/<owner>/<repo>/commits \
  -f sha=<revision> -f path=<directory-or-file> -f per_page=100
gh api repos/<owner>/<repo>/commits/<sha>/pulls --paginate --slurp

Follow additional history pages when they could resolve the question. With --paginate --slurp the result is an array of pages. GitHub PR search cannot filter by changed path; commit history and associated PRs provide that connection. Account for renames and absent mappings. Use gh pr diff or files APIs for changes and review-comment APIs for inline roots and replies.