state-management

name	state-management
description	Skill for managing review state persistence — the .review/ directory structure, state.yaml lifecycle tracking, artifact hashing, round management, and final output generation.

State Management

Use this skill when creating, reading, or updating the review state. All state lives in the .review/ directory at the submission root.

Directory Structure

.review/
├── state.yaml                 # Current phase, round number, decision history
├── config.yaml                # Review configuration (optional override)
├── profiles/                  # Reviewer profile definitions
│   ├── reviewer-alpha.yaml
│   ├── reviewer-beta.yaml
│   └── reviewer-gamma.yaml
├── rounds/
│   ├── round-1/
│   │   ├── review-alpha.yaml      # Reviewer α's report
│   │   ├── review-beta.yaml       # Reviewer β's report
│   │   ├── review-gamma.yaml      # Reviewer γ's report
│   │   ├── meta-review.yaml       # AE's synthesis
│   │   └── decision.yaml          # Editorial decision
│   ├── round-2/
│   │   ├── re-review-alpha.yaml   # Reviewer α's update
│   │   ├── re-review-beta.yaml    # Reviewer β's update
│   │   ├── re-review-gamma.yaml   # Reviewer γ's update
│   │   ├── response-letter.md     # Author's point-by-point response
│   │   ├── revision-summary.yaml  # Machine-readable change manifest
│   │   ├── meta-review.yaml       # AE's re-synthesis
│   │   └── decision.yaml          # Updated decision
│   └── ...
├── artifacts/
│   ├── hashes.yaml            # SHA-256 of all submission files per round
│   └── reproducibility.yaml   # Auditor report (if run)
└── final/
    ├── decision.yaml          # Terminal decision with justification
    ├── review-summary.md      # Human-readable summary of all rounds
    ├── score-trajectory.yaml  # Score evolution across rounds
    ├── action-items-resolved.yaml  # Audit trail: concerns → resolutions
    ├── review-certificate.md  # Summary suitable for public posting
    └── camera-ready/          # (Accept only) final paper + code package
        ├── paper_final.pdf
        ├── paper_final.tex
        └── supplementary/

State File (state.yaml)

Initial State (after intake)

phase: INTAKE
round: 0
max_rounds: 3
created: "2026-03-04T00:00:00Z"
last_updated: "2026-03-04T00:00:00Z"
submission_hash: "<SHA-256 of all files>"
venue: "NeurIPS"
paper_type: "empirical"
blinding: "single"
reviewers_dispatched: []
auditor_dispatched: false
decisions: []
terminal: false

State Transitions

Update the state file at every phase transition:

update_state() {
  PHASE="$1"
  ROUND="$2"

  # Use yq or sed to update
  yq -i ".phase = \"$PHASE\"" .review/state.yaml
  yq -i ".round = $ROUND" .review/state.yaml
  yq -i ".last_updated = \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"" .review/state.yaml
}

Recording Decisions

record_decision() {
  ROUND="$1"
  DECISION="$2"

  yq -i ".decisions += [{\"round\": $ROUND, \"decision\": \"$DECISION\", \"timestamp\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}]" .review/state.yaml
}

Artifact Integrity

Hashing

Hash all submission files at each round start to detect unauthorized changes:

hash_artifacts() {
  ROUND="$1"
  find . -type f \
    -not -path "./.review/*" \
    -not -path "./.git/*" \
    -exec shasum -a 256 {} \; > ".review/artifacts/hashes-round-$ROUND.yaml"
}

Integrity Check

Before re-review, verify the submission hasn't been tampered with outside the revision process:

verify_integrity() {
  CURRENT_ROUND="$1"
  PREVIOUS_ROUND=$((CURRENT_ROUND - 1))

  # Files that SHOULD be different (revised)
  # Files that should NOT be different (non-revised)
  diff ".review/artifacts/hashes-round-$PREVIOUS_ROUND.yaml" \
       ".review/artifacts/hashes-round-$CURRENT_ROUND.yaml"
}

Final Output Generation

Review Summary (review-summary.md)

# Peer Review Summary

## Submission
- **Title:** <from metadata>
- **Domain:** <domain> / <subdomain>
- **Venue Target:** <venue>
- **Paper Type:** <type>

## Review Panel
- **Reviewer α (Methodologist):** <focus area>
- **Reviewer β (Domain Expert):** <focus area>
- **Reviewer γ (Generalist):** <focus area>

## Round 1
### Scores
| Reviewer | Overall | Soundness | Novelty | Clarity | Significance | Reproducibility |
|----------|---------|-----------|---------|---------|-------------|----------------|
| α | X | X | X | X | X | X |
| β | X | X | X | X | X | X |
| γ | X | X | X | X | X | X |
| **Mean** | X.X | X.X | X.X | X.X | X.X | X.X |

### Decision: <decision>
<summary of key concerns>

## Round 2 (if applicable)
...

## Final Decision
**<ACCEPTED / REJECTED / EXHAUSTED>**
<justification>

Score Trajectory (score-trajectory.yaml)

trajectory:
  - round: 1
    scores:
      alpha: {overall: X, soundness: X, novelty: X, clarity: X, significance: X, reproducibility: X}
      beta: {overall: X, ...}
      gamma: {overall: X, ...}
    mean_overall: X.X
    weighted_final: X.X
    decision: "<decision>"
  - round: 2
    scores: ...
    mean_overall: X.X
    weighted_final: X.X
    delta: +X.X
    decision: "<decision>"

Review Certificate (review-certificate.md)

A public-facing summary:

# Review Certificate

**Paper:** <title>
**Venue:** <venue>
**Decision:** <decision>
**Rounds:** <N>
**Date:** <date>

This paper underwent rigorous peer review by a panel of 3 independent reviewers
with expertise in <domains>. The review process included <N> round(s) of review
and <M> revision(s).

**Final Scores:** Mean overall = X.X (range: X-X)
**Weighted Score:** X.X

**Reviewer Agreement:** <strong/moderate/weak>