The core workflow06 / 16
Read explanations and evidence
On this page
Implementation explanations help you start from a piece of intent, understand how the code works, and find evidence for that account. Focus on behavior, supporting material, and questions that still need your judgment.
Open paragraph and local explanations
Click document text to edit it. Click the blank space inside a paragraph, outside its text, to open the paragraph-level explanation, labeled L1.
Some explanations apply to a word or phrase. Hover over the paragraph to reveal short underlines, then click one to read its local explanation, labeled L2.
Lists, tables, and code blocks can also have explanations. An entire list is investigated together; headings are not investigated on their own.
You can keep margin notes open for several paragraphs. Each paragraph shows one paragraph-level or local explanation at a time. In a narrow window, its note may appear below the paragraph.
Read the three sections
| Section | Question it answers | What to look for |
|---|---|---|
| Realization | How does the implementation address this intent? | Behavior, steps, edge cases, and implementation choices. |
| Evidence | What supports the explanation? | Code references, tests, command output, and other inspectable material. |
| Attention | What needs further judgment? | Gaps, implementation choices, risks, and suggestions. |
Realization is expanded by default. Expand Evidence when needed. Attention is hidden when there are no concerns to show.
For a reward after 7 consecutive check-ins, the explanation might describe how dates accumulate, cite the relevant function and tests, and flag how travel across time zones is handled. The actual content depends on the investigation of your project.
Inspect the evidence
Code references open files in the system's default application. Images can be viewed and enlarged in the margin note. Labels for material such as command output and code diffs open a new tab. Noea tells you if the material is no longer available.
Ask whether each reference addresses your question, which conditions a test covers, and whether the results support the conclusion. If a key scenario is missing, ask about the paragraph and request further investigation or verification.
In particular, distinguish three kinds of evidence:
| Material | What it helps establish | What it does not establish |
|---|---|---|
| Implementation or test code | The logic used and the scenarios defined by tests. | The existence of tests does not mean they ran or passed. |
| Earlier execution results | What ran then, and its outcome at that time. | Later code changes may make those results inapplicable. |
| Verification actually run now | The result for this execution's environment and scope. | Passing covered scenarios does not establish correctness for untested ones. |
Explain and Investigation normally read code and existing evidence rather than rerunning tests, builds, or the app every time. They verify a fact as needed when reading alone cannot establish something essential to the judgment. Assess the verification scope from what actually ran.
To rerun a particular test, ask the Agent in chat to execute it and report its scope and result, then investigate the relevant paragraph again.
Decide which choices belong in intent
An explanation saying “The implementation currently uses local storage” describes today's approach; it does not require future versions to use it. Requirements you want to keep belong in the intent document.
Consider whether a choice affects user experience, cost, privacy, risk, or future decisions. Once you understand it, there are two common outcomes:
- The current approach is acceptable, and you want to leave room to change it later: keep using it without making it a constraint.
- The approach must remain true in future versions: write the requirement explicitly and review the limits it introduces.
For example, you might accept local storage for check-in records today. If offline use becomes essential, write “Users can still check in without a network connection,” then investigate how the implementation supports that behavior. Expressing the behavior you require is usually easier to maintain than copying a detailed implementation description.
Understand Attention
Attention items are classified as gaps, implementation choices, risks, or suggestions. They distinguish missing behavior from current design choices and topics worth further discussion.
The attention marker to the right of a paragraph opens the relevant explanation. Its number counts explanation panels containing concerns, not individual issues. A gap gives the marker a more prominent color.
Understand the impact before deciding to fix code, add verification, change intent, or keep the current behavior. Not every concern needs to become a requirement. No marker only means the current explanation lists no concerns.
Explore behavior illustrations
Some explanations include a small interactive illustration of the behavior. You can try it, reset it, or inspect its source.
These illustrations run in an isolated sandbox without access to the app or network, and do not save interaction state. They explain a rule; checking whether the real software follows it still requires code and verification evidence.
Check whether an explanation still applies
Previous text means the explanation covers intent from before your edit. May be outdated means files the explanation read or cited changed after the investigation. Both are reasons to investigate again.
Margin notes are read-only. Edit intent to change a requirement; use Investigation or Investigate Again to check an explanation. See Keep explanations up to date.