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 covers that setup.

Start the issue

Create and list the issue:

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:

tisket issue edit s4oz -s in_progress

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

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 describe the choices.

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

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.

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

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:

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:

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

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

When the work is done, close the issue:

tisket issue close s4oz

The notes outlive the issue. Zettel’s explanation describes provenance; tisket’s workflow covers scratch notes and issue status.