Packages
fnord
0.9.38
0.9.40
0.9.39
0.9.38
0.9.37
0.9.36
0.9.35
0.9.34
0.9.33
0.9.32
0.9.31
0.9.30
0.9.29
0.9.28
0.9.27
0.9.26
0.9.25
0.9.24
0.9.23
0.9.22
0.9.21
0.9.20
0.9.19
0.9.18
0.9.17
0.9.16
0.9.15
0.9.14
0.9.13
0.9.12
0.9.11
0.9.10
0.9.9
0.9.8
0.9.7
0.9.6
0.9.5
0.9.4
0.9.3
0.9.2
0.9.1
0.9.0
0.8.99
0.8.98
0.8.97
0.8.96
0.8.95
0.8.94
0.8.93
0.8.92
0.8.91
0.8.90
0.8.89
0.8.88
0.8.87
0.8.86
0.8.85
0.8.84
0.8.83
0.8.82
0.8.81
0.8.80
0.8.79
0.8.78
0.8.77
0.8.76
0.8.75
0.8.74
0.8.73
0.8.72
0.8.71
0.8.70
0.8.69
0.8.68
0.8.67
0.8.66
0.8.65
0.8.64
0.8.63
0.8.62
0.8.61
0.8.60
0.8.59
0.8.58
0.8.57
0.8.56
0.8.55
0.8.54
0.8.53
0.8.52
0.8.51
0.8.50
0.8.49
0.8.48
0.8.47
0.8.46
0.8.45
0.8.44
0.8.43
0.8.42
0.8.41
0.8.40
0.8.39
0.8.38
0.8.37
0.8.36
0.8.35
0.8.34
0.8.33
0.8.32
0.8.31
0.8.30
0.8.29
0.8.27
0.8.26
0.8.25
0.8.24
0.8.23
0.8.22
0.8.21
0.8.20
0.8.19
0.8.18
0.8.17
0.8.16
0.8.15
0.8.14
0.8.13
0.8.12
0.8.11
0.8.1
0.8.0
0.7.24
0.7.23
0.7.22
0.7.21
0.7.20
0.7.19
0.7.18
0.7.17
0.7.16
0.7.15
0.7.14
0.7.13
0.7.12
0.7.11
0.7.10
0.7.9
0.7.8
0.7.7
0.7.6
0.7.5
0.7.3
0.7.2
0.7.1
0.7.0
0.6.9
0.6.8
0.6.7
0.6.6
0.6.5
0.6.4
0.6.3
0.6.1
0.6.0
0.5.9
0.5.8
0.5.7
0.5.6
0.5.5
0.5.4
0.5.3
0.5.2
0.5.1
0.5.0
0.4.44
0.4.43
0.4.42
0.4.41
0.4.40
0.4.39
0.4.38
0.4.37
0.4.36
0.4.35
0.4.34
0.4.33
0.4.32
0.4.30
0.4.29
0.4.28
0.4.27
0.4.26
0.4.25
0.4.24
0.4.23
0.4.22
0.4.21
0.4.20
0.4.19
0.4.18
0.4.17
0.4.16
0.4.15
0.4.14
0.4.13
0.4.12
0.4.11
0.4.10
0.4.9
0.4.8
0.4.7
0.4.6
0.4.5
0.4.4
0.4.3
0.4.2
0.4.1
0.4.0
0.3.0
0.2.0
0.1.0
AI code archaeology
Current section
Files
Jump to
Current section
Files
lib/ai/agent/review/breadcrumbs.ex
defmodule AI.Agent.Review.BreadCrumbs do
@moduledoc """
Comment narrative agent. Evaluates whether comments form a coherent outline
of the code's behavior and purpose - treating the codebase as developer UX
and the comments as the documentation layer. Produces structured JSON
findings.
"""
@behaviour AI.Agent
@behaviour AI.Agent.Composite
@model AI.Model.smart()
@prompt """
You are a comment narrative reviewer. You evaluate whether the comments in
changed code tell a clear, structured story that a developer could follow
without reading the code itself.
You are a STATIC ANALYSIS agent. You review code by reading it.
Do NOT run tests, linters, compilers, or any build commands.
Do NOT execute the code under review.
## Your focus
Think of the codebase as a product and developers as users. Comments are the
UX layer that helps developers navigate, understand, and maintain the code.
Your job is developer-perspective acceptance testing of that UX.
## The narrative test
For each changed file, perform this test:
1. Read the full file with code visible. Understand what it does.
2. Now mentally hide the code and read ONLY the comments (including @moduledoc,
@doc, inline comments, and section headers).
3. Ask yourself:
- Do the comments form a structured outline of the module's behavior?
- Could a developer reconstruct the *purpose* and *flow* from comments alone?
- Are there gaps where significant behavior happens with no narrative?
- Are there sections where the comments describe trivial operations but
skip the non-obvious ones?
## What good comments look like
Good comments encode intention and rationale:
- Why this module exists and how it fits into the larger system
- Why a particular approach was chosen (especially when non-obvious)
- What the implicit contracts and assumptions are
- How data flows through the module at a high level
- What the business purpose of each significant section is
Good section headers create a table of contents:
- They divide the module into logical sections
- Reading just the headers gives you the module's structure
## What to flag
- **NARRATIVE_GAP**: A significant code section (new function, complex branch,
state transition) that has no comments explaining its purpose or how it fits
into the module's behavior.
- **ORPHAN_COMMENT**: A comment that describes a local operation without
connecting it to the module's purpose. ("Iterate over the list" instead of
"Process each pending task to determine which need retry")
- **MISSING_CONTEXT**: A new module, function, or component that doesn't explain
how it fits into the larger system. A developer finding this for the first
time wouldn't know why it exists.
- **INVERTED_DETAIL**: Comments that explain the obvious (what) but skip the
non-obvious (why). The comment budget is spent on the wrong things.
## What NOT to flag
- Missing comments on truly self-explanatory code (simple accessors, standard
patterns, thin delegation)
- Style preferences about comment formatting
- Existing comments that predate the changes (unless the changes made them wrong)
- Spelling or grammar (other reviewers handle that)
## Intent verification
Before flagging a narrative gap, verify that the "missing" context isn't
documented elsewhere or intentionally omitted:
1. **Trace callers.** Read the callers of the uncommented code. The
narrative may live at the call site or in a parent module's docs rather
than inline.
2. **Check git history.** Use `git log -p -- <file>` or `git blame <file>`
to see if a comment was deliberately removed or if the code was written
without one from the start. A removed comment may indicate the author
decided it was unnecessary.
3. **Check memories and research notes.** Use `memory_tool` (action=recall)
and `prior_research` to search for documented commenting conventions or
rationale for the code area.
If any of these steps reveals that the omission is intentional or that the
narrative lives elsewhere, it is not a finding.
A narrative gap is only a real finding when it hides an important workflow,
invariant, state transition, or integration point that a developer needs in
order to understand the changed code safely. Missing commentary on
self-explanatory or locally obvious code is not a finding.
## Pre-provided scope data
Your Review Scope (above) already contains a git range and diff stat provided by
the decomposer. Use them directly. Do NOT run `git diff --stat` to re-derive
information already in your scope.
If you believe you need to run `git diff --stat` or `git log` anyway, you MUST
first call `notify_tool` explaining why the pre-provided data is insufficient.
This is a hard requirement.
## Method
1. Use the diff stat from your Review Scope to identify changed files.
2. For each changed file, read the FULL current file (not just the diff).
You need the full context to evaluate narrative coherence.
3. For new files: evaluate the complete comment narrative.
4. For modified files: focus on changed/added sections, but consider whether
the changes disrupted the existing narrative flow.
Do NOT report on files you did not actually read.
Populate `trigger_scenario`, `reachability_analysis`, `source_of_truth`, and
`producer_chain`. For comment-only findings, explain the developer workflow or
integration point affected, and use `N/A - mechanical finding` when no
producer chain applies.
"""
@review_prompt "Read every changed file in full. Evaluate the comment narrative. Produce your findings."
# ---------------------------------------------------------------------------
# AI.Agent behaviour
# ---------------------------------------------------------------------------
@impl AI.Agent
def get_response(args) do
AI.Agent.Composite.run(__MODULE__, args)
end
# ---------------------------------------------------------------------------
# AI.Agent.Composite behaviour
# ---------------------------------------------------------------------------
@impl AI.Agent.Composite
def init(%{agent: agent, prompt: prompt, scope: scope}) do
tools = AI.Tools.basic_tools()
user_prompt = "## Review Scope\n#{scope}\n\n## Instructions\n#{prompt}"
state = %AI.Agent.Composite{
agent: agent,
model: @model,
toolbox: tools,
request: scope,
response: nil,
error: nil,
messages: [
AI.Util.system_msg(AI.Util.project_context()),
AI.Util.system_msg(@prompt),
AI.Util.user_msg(user_prompt)
],
internal: %{},
steps: [
AI.Agent.Composite.completion(:review, @review_prompt,
response_format: AI.Agent.Review.Reviewer.specialist_response_format()
)
]
}
{:ok, state}
end
@impl AI.Agent.Composite
def on_step_start(_step, state) do
UI.report_from(state.agent.name, "Evaluating comment narrative")
state
end
@impl AI.Agent.Composite
def on_step_complete(_step, state), do: state
@impl AI.Agent.Composite
def get_next_steps(_step, _state), do: []
@impl AI.Agent.Composite
def on_error(_step, _error, state), do: {:halt, state}
end