Skip to main content

Reviewer guide

This guide is for people reviewing work in AetherFS.

Your job is usually not to create the platform or operate the service. Your job is to inspect a session, understand its state, decide whether the work is acceptable, and leave clear feedback.

What matters most in this role​

As a reviewer, the highest-signal concepts are:

  • session
  • manifest
  • annotation
  • approval
  • health
  • event history

You usually do not need to think deeply about source creation, advanced sparse mutation, or Aether CLI cache tuning.

Your core workflow​

The normal reviewer flow is:

  1. open the session
  2. inspect the session status
  3. inspect the filesystem tree
  4. read existing annotations
  5. add or resolve annotations
  6. inspect health and recent events if needed
  7. grant or deny approval

Read these pages first​

Start here:

Then use these references as needed:

What to look at first when you open a session​

Session status​

If the session is:

  • SESSION_STATUS_PENDING_APPROVAL: your decision is likely blocking the next step
  • SESSION_STATUS_CONFLICT: do not treat approval as the only question
  • SESSION_STATUS_PENDING_REVIEW: expect an active review workflow

Manifest​

The manifest gives you the tree and path structure.

Use it to answer:

  • what files exist
  • where the relevant changes or notes are
  • which subtree to review first

Annotations​

Annotations are your main review-note surface.

Use them for:

  • file comments
  • unresolved issues
  • marking notes as resolved

Health​

Health tells you whether the last reported test state is unknown, passing, or failing.

Use it as evidence, not as the entire decision.

Events​

The event log helps when you need to understand what happened over time rather than only what currently exists.

How to write good review feedback​

Use annotations for:

  • concrete file-level concerns
  • missing cases
  • requests for follow-up changes
  • resolved versus unresolved note state

Use denial feedback for:

  • the high-level reason approval was denied
  • what must happen before the work returns for approval

Do not force all detailed commentary into approval-deny feedback when it really belongs in per-file annotations.

When to approve​

Approve when:

  • the filesystem state looks acceptable
  • the annotations are addressed or explicitly understood
  • health is good enough for the workflow
  • there is no unresolved reason to block persistence or promotion

When to deny​

Deny when:

  • unresolved review issues remain
  • the health state is not acceptable for the workflow
  • the requested action is too high-impact for the current evidence
  • the session should be revised and resubmitted

Common reviewer mistakes​

Avoid:

  • using tags as if they are comments
  • treating health as automatic approval
  • leaving actionable detail only in chat or email instead of annotations
  • ignoring stale-content risk on file comments

Fastest useful review toolkit​

If you only remember the key routes:

  • session detail
  • manifest
  • annotations
  • health
  • approval grant/deny
  • event log

That is enough to perform a strong review without learning the entire platform surface.