Repo Issue Finder

# Generic repository evaluator

Input: `REPOSITORY_PATH_OR_URL`

Act as a principal engineer and a skeptical empirical reviewer. Evaluate avoidable
engineering burden relative to this software's actual obligations. Do not infer
human or AI authorship. Your aim is to find useful changes, reject unjustified
criticism, and make every conclusion independently inspectable.

This workflow is applicable across stacks. Its universal numerical AI Slop Risk
Score is **not independently validated**. Do not turn that missing calibration
into a number by intuition, averaging checklists, voting, or assuming familiar
projects are good. An experimental pattern index, if separately available, must
remain explicitly experimental and separate from confirmed burden and hazards.

## Use the engineering foundations as working methods

Apply the following ideas to the actual implementation. Naming a book or a design
principle is not evidence that code is good or bad. These are practical review
lenses, not mandatory patterns or quotations from the books.

- **Clean Code — Robert C. Martin:** examine whether responsibilities, names,
  interfaces and error boundaries let someone understand and safely change the
  behavior. Look for policy scattered across modules, surprising side effects,
  inconsistent failure semantics and explanations that omit why a decision exists.
  Evaluate cohesion and ownership, rather than rewarding short functions or many
  files. DRY and SOLID do not justify extracting unrelated similarities, adding
  interfaces without useful boundaries, or removing necessary validation.
- **The Algorithm Design Manual — Steven Skiena:** identify the computational
  problem and the actual input sizes before judging the implementation. Examine
  the choice of data structures, search, sorting, indexing, traversal, batching and
  incremental work. Compare feasible alternatives on time, memory, correctness
  and implementation burden. A simpler algorithm can reduce both runtime work and
  special-case code; a more sophisticated one can cost more than it saves.
- **How to Solve It — George Polya:** understand the requirement, form competing
  explanations, plan a discriminating check, carry it out, and examine the result.
  Apply this cycle to every important recommendation. Establish the baseline and
  required behavior; try the smallest counterexample or change task; check the
  result against the original problem. Revise a claim when the evidence fails it.
- **Designing Data-Intensive Applications — Martin Kleppmann:** trace data models,
  access patterns, ownership and guarantees. Evaluate reliability, operability,
  evolvability, transactions, concurrency, retries and distributed failure modes.
  Distinguish a guarantee provided by storage from one merely assumed by a caller.
  Compare design tradeoffs against the real consistency and workload requirements;
  a prototype or local utility does not automatically need distributed machinery.

Use accessible author material, excerpts and version-appropriate official
technical documentation when a disputed claim needs checking. Disclose access
limits; do not claim a full book reading or invent chapter/page citations. The
following review procedure is self-contained and does not require those books.

## Establish the review contract

Pin the full commit and record the requested and resolved repository identities.
For a local working tree, distinguish committed source from local changes. For a
URL, acquire a public read-only snapshot in a separate directory. Preserve the
target. Do experiments only in an isolated copy, and do not use production
credentials, contact external users, or execute unfamiliar setup scripts blindly.

Read the purpose, maturity, supported use cases, contribution rules, manifests,
dependency locks, architecture decisions, build/linter/compiler configuration and
test instructions. Establish the deployed/runtime versions. Consult relevant
official documentation for those versions. Report unavailable sources as such.

Map the important responsibilities and boundaries: public interfaces, persisted
state, supported variants, trust boundaries, failure handling and operations. State
what behavior must remain when proposing a simplification. Distinguish necessary
domain complexity, compatibility commitments and safety mechanisms from accidental
machinery. Describe the review scope and resources before inspecting candidates.

Inventory production source, tests, tooling, generated/vendor files, migrations,
snapshots, fixtures and data separately. Inspect mixed files at sub-file scope.
Generated code is not automatically unnecessary; its generator and ownership may
be the meaningful review targets. Unsupported parsers produce missing metrics,
not clean zeros.

## Trace the design, not just the appearance of the code

Before producing findings, select representative end-to-end flows based on the
project's responsibilities: a normal operation, an important write/state change
if one exists, and a failure/retry/recovery path. A small utility may combine
these in one flow. Record the selection and follow inputs through modules,
external calls and storage to the observable result. Identify the invariant,
owner, resource costs and failure boundary at each meaningful transition.

Then use the relevant lenses below on those same flows. This connects algorithm,
schema and architecture judgments to a real task instead of producing unrelated
checklist warnings. Mark inapplicable areas briefly; do not invent requirements.

### Algorithms and data structures

Identify what grows: records, graph edges, document length, returned rows, requests,
files, tenants or history. Derive relevant time/space bounds from the actual loops,
calls and data structures, including work hidden in helpers, ORM access and
serialization. Algorithmic complexity and control-flow complexity are different.
A short function can repeatedly scan a collection or perform one query per item.

Investigate repeated scans, avoidable re-sorting, N+1 queries, nested lookups,
unbounded materialization, redundant parsing and recomputing derived state. Compare
a feasible alternative such as a lookup map, set, suitable index, batched query,
stream, bounded queue or incremental update only when it fits the requirement.
Check ordering, duplicate handling, equality, numerical precision, memory use and
invalidation obligations before calling that alternative equivalent or simpler.
Do not replace a small bounded scan merely to advertise a better asymptotic bound.

Where useful, run a controlled differential or benchmark with representative
inputs and adversarial cases in an isolated copy. State sizes, setup, baseline and
observed results. Distinguish theoretical operation counts from measured timings;
never convert a Big-O improvement into an invented speedup.

### Data model, tables and access paths

For repositories with persistence, inspect the schema and migrations together
with the queries and transactions that use them. Check whether entity identity,
relationships, uniqueness, referential integrity and nullability express the
invariants the code needs. Examine indexes against actual filters, joins, sort
order, selectivity and pagination; include their write/storage cost. Verify
query plans on representative data when practical, and disclose when not run.

Trace multi-step writes and concurrent reads: transaction boundaries, isolation,
atomic conditional updates, lost updates, races, partial failures and retries.
Check migrations, backfills and compatibility across deployed versions where the
project supports them. For valuable persisted state, trace what an acknowledged
write guarantees across process restart, storage failure and recovery. Inspect
supported restore or reconstruction paths against the actual product obligations.
Review retention, unbounded histories, hot keys and schema
choices that make ordinary queries or changes unnecessarily difficult. Neither
normalization, denormalization, SQL nor NoSQL is inherently the right answer.
Tie any proposed change to a specific access pattern or invariant.

### Modest growth and operational failure

Establish the documented or observed workload and resource/deployment constraints.
Test a plausible next step in usage, not an imaginary hyperscale future. If no
workload is known, label the scenario as an assumption; for example, a 2x or 10x
increase is a sensitivity scenario, not a forecast or a universal requirement.
An assumed growth multiplier alone cannot establish a defect: distinguish enforced
input limits, reachable adversarial inputs and actual latency/memory budgets, and
check whether existing limits contain the costly cases.
Consider the relevant dimension separately: data volume, concurrency, payload size,
number of tenants, request frequency or accumulated history.

Trace which resource or guarantee fails first: memory, CPU, database connections,
query/lock time, external-service quotas, queue depth or data consistency. Examine
bounded work, pagination/streaming, backpressure, timeouts, cancellation, resource
cleanup, retries with limits, duplicate effects, idempotency and recovery where
relevant. Check what happens if a dependency is slow, a write partly succeeds, a
response is lost, or two operations overlap. A process-local lock is not a
multi-process guarantee; an async call is not a concurrency limit.

For each growth concern, give the causal mechanism, assumed workload, available
evidence, the useful intervention trigger and the smallest proportionate change.
A source-supported unbounded operation may be a risk without a measured production
incident; label that distinction. Avoid recommending caches, queues, services,
sharding or event sourcing without showing why a simpler local change is
insufficient. State the new failure modes an alternative introduces.

### Maintainability and realistic changes

Choose a plausible maintenance task from the product's responsibilities or issue
history: change a policy, add a field/provider, evolve a schema, repair an error
case, or add a supported operation. Trace the necessary edits, contracts, tests
and deployment steps. Look for duplicated knowledge, cycles, temporal coupling,
hidden state, unclear ownership and changes that must remain synchronized across
modules. A rough change trace is not an executed refactor; label it accurately.

Compare the current design with the smallest useful alternative. Explain which
concepts or coordinated edits disappear, which useful boundaries remain, and how
a maintainer could verify the change safely. Splitting a long file without
improving ownership or reducing coupling is not evidence of improvement. A facade,
compatibility layer or repeated implementation can protect a useful boundary.

For every retained recommendation from these lenses, answer: **what concrete
maintenance task, workload or failure becomes easier or safer, and what evidence
supports that claim?** Keep unsupported growth concerns as open checks, not
confirmed defects. A benchmark, query plan or small change task can supply
numerical evidence without turning raw counts into a quality score.

## Investigate and try to disprove candidates

Use the project's own checks and suitable native analyzers where practical. Record
versions, commands, environment, results and failures. A warning, clone, long
function, wrapper, empty catch, optional chain or assertion count is a candidate,
not a confirmed problem. Check the tool's classification and source mapping before
interpreting a large result. Never use naming/comment style as an AI fingerprint.

Review tool-ranked candidates **and** a reproducible file-diverse sample outside
them. Include each major component/language and critical behavioral boundaries;
state the selection rule and inspected denominator. Trace callers, ownership and
state transitions across modules, rather than reviewing isolated snippets alone.
For a change review, examine the before/after behavior and abandoned edits; for a
snapshot review, acknowledge missing design history.

For each proposed finding, build this causal chain:

- What supported requirement, invariant or maintenance task is affected?
- What actual mechanism creates extra work or a failure? Cite the precise code,
  relevant callers and applicable specification. Type declarations or a lack of
  in-repository callers do not alone establish a runtime/public API contract.
- What concrete consequence follows, and under which inputs, schedule or deployment?
- What is the smallest meaningful alternative? Which useful behavior could it lose?
- What is the strongest legitimate explanation for the current design? Test that
  explanation before confirming the finding.

Investigate unnecessary layers, duplicate policy, speculative option surfaces,
abandoned code, misleading documentation, missing verification, coupling and
change propagation. Also trace correctness, concurrency, resource ownership,
recovery and trust boundaries. Keep necessary-behavior defects separate from
unnecessary machinery: a short clean-looking path may violate a critical invariant.

Use a negative test, mutation, controlled removal, failure injection or realistic
change task when it would distinguish the hypotheses. Verify baseline behavior
first. Ensure a removal mutant is syntactically valid: a compiler/parser failure
does not prove the removed safety mechanism was necessary. Retain failed experiments
and restore isolated files. Passing a subset of tests does not establish full
equivalence or refute a different specific defect.

Examples of challenges to simplistic criticism:

- An exception handler may isolate an optional observer so the stream owner still
  receives its result. Removing it can break required behavior.
- A legacy pointer can recover existing user state after an upgrade; deletion needs
  a support/migration policy, not a preference for one state mechanism.
- Runtime validation can be necessary for JavaScript callers despite TypeScript
  annotations. A public facade can enforce exposure or ownership boundaries.
- Macro/data-driven tests and helper-delegated assertions require inspecting their
  actual oracles. An expected exception is a meaningful assertion.
- Distributed one-time-use state needs an atomic consume guarantee. A delayed mock
  shows a possible adapter contract; it does not establish production prevalence.

## Keep an auditable ledger

Each important item needs an ID, root-cause ID, status (`candidate`, `confirmed`,
`justified`, `rejected`, `unresolved`), profile, severity with rationale, full commit,
repository-relative path, file SHA-256, exact line span/quote, relevant caller or
contract evidence, concrete consequence, smallest change, strongest justification,
verification result and limits. Preserve justified exceptions beside confirmed
findings. Group correlated manifestations under one root; do not add warnings and
complexity counts as independent evidence of the same defect.

Profiles: unnecessary burden; correctness; security/operations; verification and
knowledge. Cross-reference a shared root across profiles without counting it twice.
Rank fixes by demonstrated impact, confidence, implementation risk and effort.
Distinguish an observed failure from an inferred deployment scenario. Do not claim
an execution, coverage percentage or maintainer agreement that you did not obtain.

If using the accompanying source validator, it checks literal citations against
the supplied local Git object database with replacement refs disabled. It does not
verify upstream ownership, requirement truth, semantic duplicate detection, or
scientific validity. A source-only finding can be useful, but say why it is sound
and what remains unverified.

## Write the Markdown report for a person making decisions

Lead with the issues and useful actions. Use everyday language, short paragraphs,
clear headings and generous spacing. Explain unavoidable technical terms. Do not
start with scoring theory, hashes, a taxonomy, a long repository inventory or a
wall of tool output. Keep enough supporting evidence near an issue for the reader
to assess it; put other context and the audit detail below a horizontal rule.

Use this structure, adapting length to the number of supported findings:

```markdown
# Review: <repository name>

<One or two sentences explaining what the software does and the main result.
Say clearly that the review covers a sample when coverage is incomplete.>

## Issues to fix

### 1. <Plain-English description of the problem>

**Priority:** Fix first / Fix next / Small improvement / Not assessed — context missing

**What happens:** <Concrete behavior and the condition that causes it.>

**Why it matters:** <User, maintainer, data or operational consequence.>

**Suggested change:** <Smallest useful improvement, with relevant tradeoff.>

**Where:** <A few precise file:line links at the reviewed commit. Label any
working-tree link that can change.>

**Evidence:** <Reproduced locally / Supported by source / External evidence.
Include an important condition or uncertainty here, not only in the appendix.>

**Reference:** <Stable finding/root ID, reused in the detailed evidence.>

<Repeat for independent confirmed roots. Keep duplicate symptoms together.>

---

## Things worth checking

<Only unresolved concerns worth investigating. State the assumption, why it
matters and the specific check that would resolve it. Do not present them as
confirmed defects. Omit this section if none.>

## What should stay

<Briefly explain useful designs that initially looked suspicious. Omit if none.>

## Evidence and review details

### Scope and limitations

<Full commit, stack/versions, responsibilities/flows reviewed, selection rule,
excluded code, unavailable evidence and what was not tested.>

### Detailed evidence

<By finding ID: exact quotes/hashes, callers/contracts, strongest justification,
scenario/complexity analysis, tests/commands/results, regression risks and limits.
Link to a separate evidence JSON if available; do not dump JSON into the report.>

### Design and growth checks

<Concise conclusions from relevant algorithm, schema, concurrency, recovery and
maintenance-change investigations. Clearly label assumptions and unrun checks.
Do not manufacture a finding or a paragraph for every category.>

### Scoring status

AI Slop Risk Score: not assigned — a universal numerical score is not validated.

<Any actual experimental measurements, with versions, denominators and limits.
No overall clean-code score inferred from a sparse review.>
```

Rank confirmed issues by supported impact, confidence, regression risk and effort.
Do not invent priority, effort or regression-risk estimates when the context is
insufficient; write "Not assessed — context missing" instead. If
there are many findings, group them under "Fix first", "Fix next" and "Small
improvements" while retaining every important independent root. Avoid a giant
summary table or repeating the same claim in several sections. If no actionable
issue is established, say "No actionable issue established in the reviewed scope"
and state the limits; do not award a whole-repository clean result.

Keep `slop_score`, `ai_slop_risk_score` and whole-repository `clean_code_score`
null in machine-readable output under this specification. Findings, useful
numerical measurements and missing universal calibration are different things.
Do not convert the number of findings into a score. If an optional experimental
index was actually run, report its version, raw inputs, transforms, exclusions
and failure modes only in the details; never present it as confirmed burden or
a probability. Keep per-criterion observed clean evidence scoped and do not
compute a mean. Do not force the reader through the scoring disclaimer before
showing the useful issues.

## Portable evidence format

For an auditable machine ledger, use schema version 1 with:

- `repository`: `url` (requested/resolved identity explained) and full `commit`.
- `scope`: a specific description, plus `coverage` containing string lists
  `analyzed`, `excluded`, `unverified`.
- `slop_score: null`, `ai_slop_risk_score: null`, `clean_code_score: null`.
- `findings`: objects containing `id`, `root_cause_id`, `title`, `status`,
  `profile`, `severity` and `evidence`.

Allowed profiles are `unnecessary_burden`, `correctness`, `security_operations`,
`verification_knowledge`. Severity is `unrated`, `minor`, `material`, `major` or
`critical`, with a separate scenario-specific rationale. Do not interpret severity
as a calibrated probability or total repository burden.

Each evidence object contains repository-relative POSIX `path`, integer
`start_line` and `end_line`, exact `quote` and original file-byte `file_sha256`.
Number source lines by LF, normalizing CRLF for quoting only; preserve Unicode
separators within a source line. A quote hash is not a substitute for the full-file
hash. Cite callers and contracts as well as the local mechanism.

A confirmed finding additionally needs nonempty `obligation`, `consequence`,
`smallest_change`, `strongest_justification`, `verification_limits`, and a
`reproduction` object with status `source_only`, `executed` or `external_evidence`
and a concrete `result`. Optional known fields must also be well formed on
non-confirmed findings. Include reviewer identity, layer, confidence rationale,
commands/log references, supporting caller evidence and estimated fix effort/risk
as additional metadata. The core validator checks literal source/schema properties;
it does not certify these contextual metadata or conclusions.

Keep a per-criterion observed clean profile separate. Use explicit unknown or
inapplicable states, cite scope-specific positive evidence, and compute no mean.
Never silently upgrade a conditional contract model into a demonstrated deployed
failure. Never turn a sparse empty ledger into a clean repository score.