adrai Review Notes

Personal annotation layer for adrai artifact review with debate promotion

GitHub | MIT License | by sprantic

The Problem

Reviewers have fleeting thoughts during review that don't warrant formal debates:

• Knowledge questions ("what does X mean?")
• Uncertainties ("not sure about this yet, need to read more")
• Bookmarks ("come back to this")
• Pre-debate concerns ("might be a problem, but not sure")

Current state: People keep text files open in notepad. No structured capture.

The Solution

This VS Code extension provides:

• Sidebar panel showing all notes grouped by status/type
• Quick note creation at current cursor position
• Multi-location linking (one note → multiple files)
• Personal storage in ~/.adrai/review-notes.yaml (gitignored)
• Promotion workflow to create DEB-NNNN from notes

Usage

Keyboard Shortcuts

Note Types

Note Lifecycle

open → investigating → promote → resolved
                    ↘         ↗
                      resolved

Multi-Location Notes

A single note can reference multiple file locations:

1. Create note with Ctrl+Shift+N
2. Navigate to another relevant location
3. Press Ctrl+Shift+L and select the note
4. The note now shows both locations

This is useful for:

• Tracking related code across files
• Linking interface definitions to implementations
• Connecting documentation to code

Promoting to Debate

When a note warrants formal discussion:

1. Right-click the note → "Promote to Debate"
2. Extension reads .deb-tracker.md for next ID
3. Creates DEB-NNNN file from template
4. Pre-fills the central question from note content
5. Links all note locations as context
6. Marks the note as resolved with promoted_to: DEB-NNNN

🏗️ This function is currently incomplete and just a teaser for the collaborative support of adrai 🏗️

When to Promote: The 3-Gate Flow

Apply the 3-Gate criteria to decide if a note should become a formal debate:

If NO to all gates: Standard MR review continues. If ANY gate triggers: Use "Promote to Debate" to create DEB-NNNN.

See docs/RITUALS.md for the full development workflow.

Configuration

In VS Code settings (settings.json):

{
  "adrai.storageLocation": "~/.adrai/review-notes.yaml",
  "adrai.debateTemplateDir": "docs/debates/templates",
  "adrai.debatesDir": "docs/debates",
  "adrai.groupBy": "status"
}

Storage Format

Notes are stored in YAML for human-readability:

version: "1.0"
notes:
  - id: "uuid-1"
    content: "What does risk level actually mean here?"
    type: question
    status: open
    created: "2026-01-29T14:30:00Z"
    updated: "2026-01-29T14:30:00Z"
    locations:
      - file: "docs/debates/README.md"
        line: 48
        preview: "| Risk | Approvers Required |"
      - file: "docs/debates/templates/plan-template.md"
        line: 187
        section: "Risk Level Guidelines"
    tags: [terminology]
    promoted_to: null

Commands

All commands are available via Command Palette (Ctrl+Shift+P):

Context Menu

Right-click on a note in the panel for:

• Add Location (link current cursor to this note)
• Promote to Debate
• Resolve Note
• Edit Note
• Delete Note

Right-click in the editor for:

• Add Review Note

Status Bar

The status bar shows the count of open notes. Click to focus the panel.

Integration with adrai

This extension is part of the adrai (AIDE Notes Review Lifecycle Management System):

• Notes capture fleeting thoughts during artifact review
• Multi-location linking connects related code/docs
• Promotion workflow creates formal debates when warranted
• Personal storage keeps notes out of version control

See the adrai project documentation for the full system design.

License

MIT (c) 2026

sprantic GmbH