---
title: "How to keep an issue's research in notes"
description: "Link an issue to its research notes and review agent findings before using them."
type: how-to
canonical_url: https://eng.rip/how-to-keep-an-issues-research-in-notes/
---

# How to keep an issue's research in notes

Start in a repository with tisket and zettel initialized. [Set up a repository with tisket, zettel, diataxis, and gaff](<set-up-a-repository.md>) covers that setup.

## Start the issue

Create and list the issue:

```sh
tisket issue create "Retry failed uploads" -l uploads
tisket issue list
```

Creation prints nothing. The list shows `s4oz-retry-failed-uploads` in this example. Use your own issue and note prefixes in the commands below.

Mark the issue as in progress:

```sh
tisket issue edit s4oz -s in_progress
```

## Link each finding both ways

Create a note with the issue's prefix as a tag:

```sh
zettel note create "Upload client drops 503 responses" -t uploads,s4oz -p agent:summary -b "The client treats a 503 as final and does not retry."
```

The command prints `isci-upload-client-drops-503-responses`. The `s4oz` tag connects the note to the issue.

Use `agent:summary` for this finding; [zettel's provenance labels](https://zettel.eng.rip/what-is-zettel/) describe the choices.

Append the note's ID to the issue's scratch notes, then list the notes tagged with the issue prefix:

```sh
tisket scratch s4oz append "Findings: zettel note isci."
zettel note list --tag s4oz
```

The list prints:

```
isci-upload-client-drops-503-responses  agent:summary  [uploads, s4oz]  Upload client drops 503 responses
```

The scratch line connects the issue to the note. It sits under `## Scratch Notes` in the issue file and leaves the body unchanged.

## Review agent text

List unreviewed notes and inspect the note's spans before relying on its findings:

```sh
zettel note list --unreviewed
zettel note review isci
```

The review command lists the span:

```
1  agent:summary (default)  The client treats a 503 as final and does not retry.
```

Only a human runs `--approve`. After checking the claim, approve the span with your reviewer name in place of `cody`:

```sh
zettel note review isci --approve all --reviewer cody
```

The command prints `1 span(s) approved` and stamps the text with `reviewed=<date> reviewer=cody`.

Read the issue's research with a provenance filter:

```sh
zettel read --tag s4oz --provenance human,citation,reviewed
```

The read returns only text a human wrote, quoted, or approved.

## Close the issue

When the work is done, close the issue:

```sh
tisket issue close s4oz
```

The notes outlive the issue. [Zettel's explanation](https://zettel.eng.rip/what-is-zettel/) describes provenance; [tisket's workflow](https://tisket.eng.rip/workflow/) covers scratch notes and issue status.