By Thirteenfold Systems · Updated 8 September 2026

Review a repository: evidence, examples, and unknowns

Use a repository-review checklist and handoff template. Reproduce a C++ example, compare requirements with evidence, and record findings, tests, and unknowns.

What makes a repository review useful?

Tie one question to a specific revision and selected requirements, implementation, and tests. Record what the excerpts show, what was not inspected, and whether any tests actually ran before proposing the next check.

Download text template

Step 1

Ask one answerable question

Start with a behavior, requirement, or small decision. Name the repository revision and the scope you are authorized to inspect. A narrow question makes missing evidence easier to identify.

Example: does this validation function meet the documented requirement?
Avoid a request to inspect every file without a purpose.
Keep execution and modification authority separate from permission to read.

Step 2

Select the evidence

Choose the relevant specification, function, and tests. Keep file names, excerpt boundaries, and revision information. Exclude credentials, generated dependencies, private customer material, and unrelated source.

Mark excerpts as excerpts.
Keep the specification separate from observed implementation.
A test file shows intended checks; it does not prove the tests ran.

Step 3

Write down what you cannot determine

A caller may transform an input, a dependency may change behavior, or a missing test may cover the case elsewhere. State what additional inspection would resolve the question.

Use “not present in the selected evidence” instead of claiming something does not exist.
Distinguish reasoning from an executed result.
Give the reviewer a bounded next check.

Step 4

Hand off a reviewable packet

Include the question, scope, evidence, finding, uncertainty, and proposed next check. Review redactions before sharing. The packet supports a decision; it does not grant authority to apply a fix.

Retain original evidence privately.
Keep source provenance with the excerpts.
Record tests as unexecuted unless you have the corresponding run evidence.

Synthetic repository · no tests executed

Does this name check match its requirement?

This fictional snapshot contains selected excerpts from three files. It demonstrates a focused review without claiming to establish the behavior of a whole application.

Snapshot: sample-snapshot-1 (fictional label, not a Git commit)
Question: Does valid_name enforce the documented requirement?
Scope: The three excerpts below.

README.md — selected requirement
A project name must contain at least one non-space character.

src/settings.py — selected function
def valid_name(value):
    return len(value) > 0

tests/test_settings.py — selected assertions
assert valid_name("example") is True
assert valid_name("") is False

The requirement concerns non-space characters. The displayed function checks only string length.
By inspection, passing three spaces directly to this function would return True. This is reasoning from the snippet, not a recorded execution.
The selected assertions do not cover a spaces-only name. Other tests may exist, and a caller may normalize or reject the input first.

Copyable example · static reasoning

Turn the finding into a bounded next check

Inspect the immediate caller within the agreed scope. If this function is intended to enforce the requirement, propose the spaces-only test below for review.

Finding:
The selected function checks length. The selected requirement
calls for at least one non-space character.

Evidence:
README requirement, src/settings.py function, and the two
displayed assertions from sample-snapshot-1.

Uncertainty:
Caller behavior and the rest of the test suite were not inspected.

Proposed next check:
Review the immediate caller and clarify where the requirement
must be enforced before deciding on a change.

Proposed requirement check — not executed:
assert valid_name("   ") is False

Execution: None.
Source changes: None.

The proposed assertion would fail against the displayed function as written. It expresses the intended requirement; it is not evidence of a passing test.
A reviewer can decide whether more inspection, an authorized test run, or a code change is appropriate.

Blank repository-review handoff template

Use the text below to record your review. Complete only relevant fields, and review the record itself before sharing.

REPOSITORY REVIEW HANDOFF
Thirteenfold Systems | Revised 2026-09-08
Guide: https://www.thirteenfoldsystems.com/guides/repository-review

Use public-safe excerpts. Write "not inspected" or "not run" when appropriate.

QUESTION AND AUTHORITY
One question this review should answer:
Permission to inspect:
Permission to execute code or change files (do not infer from read access):

EVIDENCE IDENTITY
Repository or safe descriptive label:
Exact revision:
Selected files and line ranges:
Requirements or specification:
Scope exclusions:

FINDING
What the selected evidence directly shows:
Inference and its reasoning:
What remains unknown:

TEST EVIDENCE
Execution status: not run
If run, exact command and environment:
If run, observed output and exit status:
What the check does and does not establish:

HANDOFF
Proposed next check:
Decision needed:
Redactions or transformations applied to shared excerpts:
Review date:

This record does not grant permission to execute, modify, merge, or release.

Executed teaching example · C++20

Reproduce a length-only validation defect in C++

This separate, original teaching program calls a deliberately incomplete function with an ordinary name, an empty string, and three ASCII spaces. Its example requirement is precise: at least one character other than ASCII space U+0020. It is not a test of Trace or of the fictional Python repository above.

The program was compiled and run on 8 September 2026 using GCC 13.3.0 on Linux x86_64. These are the recorded results:

ordinary: observed=true, required=true
empty: observed=false, required=false
three ASCII spaces: observed=true, required=false
Requirement mismatches: 1 of 3

The spaces-only input is accepted by the function and contradicts this requirement. The program exits with code 0 when it reproduces exactly this one mismatch; that exit code does not mean the validator meets the requirement. These three cases establish no behavior for a complete application, Unicode whitespace policy, or native Windows build.

Download the C++ teaching source (text)

Source and reproduction details

With a C++20 compiler installed, reproduce this in a Linux shell from the directory containing the downloaded text file:

g++ -std=c++20 -Wall -Wextra -Werror -x c++ repository-review-example.cpp.txt -o repository-review-example
./repository-review-example

Source SHA-256: bc383b2b371d6e8b378783943e7456a3e017931c0ed6841c0ae0341253df6edb

// Standalone teaching example, not Trace source or a product qualification.
// Requirement: contain at least one character other than ASCII space U+0020.
// This demonstrates a deliberately incomplete length-only implementation.
#include <iostream>
#include <string_view>

bool valid_name(std::string_view value) { return !value.empty(); }

int main() {
    struct Case { const char* label; std::string_view input; bool required; };
    constexpr Case cases[] = {
        {"ordinary", "example", true},
        {"empty", "", false},
        {"three ASCII spaces", "   ", false}
    };
    int mismatches = 0;
    std::cout << std::boolalpha;
    for (const auto& item : cases) {
        const bool observed = valid_name(item.input);
        std::cout << item.label << ": observed=" << observed
                  << ", required=" << item.required << '\n';
        if (observed != item.required) ++mismatches;
    }
    std::cout << "Requirement mismatches: " << mismatches << " of 3\n";
    // Success means the teaching example reproduced its one expected defect.
    return mismatches == 1 ? 0 : 1;
}

Next, inspect the relevant caller and decide where the requirement belongs before proposing a fix. Use the review handoff template to keep the finding, execution evidence, and unknowns together.