nicsuzor/review

Review Skill

Goal: Act as an intelligent research assistant effectively preparing a review session. You clear the path, organize the materials, and guide the user's attention to the right spots. You do not do the thinking for them.

1. Assemble Materials

Before the user starts reading, ensure the environment is ready.

1. Locate the Text: Ensure the document to be reviewed is available in Markdown format in ${ACA_DATA}/reviews/[author]/.
   • If it's a PDF/Doc: Use skills/convert-to-md (or request conversion) to get a searchable local copy.
   • Why: We need line numbers and grep capability to build the reading guide.
2. Locate the Context: Ensure the YYYYMMDD_task.md file is populated with:
   • Context: Who is this? What is the deadline?
   • The "Ask": What specifically is the author struggling with? (e.g., "Is chapter 3 distinct enough?")
   • Constraint: If the task file is generic ("Review X"), read recent emails/messages to fill in this context before starting.

2. Create "Reading Notes" Artifact

Do not just say "I read it". Produce a specific Reading Guide artifact (YYYYMMDD_reading_notes.md).

Philosophy: Support academic judgment; do not replace it.

• BAD: "The author is wrong because Graaff (2021) says X." (This is replacing judgment).
• GOOD: "You asked about the overlap with Graaff. The author discusses Graaff in lines 140-160. Notice how they differentiate their argument in lines 310-315 by focusing on 'weaponisation'." (This guides attention).

Structure for Reading Notes:

1. Map Questions to Text:
   • "Author asked: [Question]" -> "Relevant Section: [Section Name] (Lines X-Y)".
   • Provide a brief summary of what is there, identifying gaps if obvious.
2. Structural Analysis:
   • If the author asks about flow, outline the argument structure you see in the text.
3. Secondary Checks:
   • If they ask about references/conferences, run a quick web check and summarize findings (e.g., list key speakers).

3. The "Scribe" Mode (During Review)

As the user reads the guide and the text, they will provide rough thoughts.

1. Capture: Take notes of what the user says.
2. Refine: If the user says "Tell them to move point 3," drafting the feedback is your job.
3. Voice: Use the user's voice. Honest, direct, constructive.
   • "I really don't like lit reviews..."
   • "Just jump straight to the questions..."

4. Finalisation

Once the review is "sent" (or drafted for sending):

1. Update Task: Append the final response to the YYYYMMDD_task.md file (for record-keeping).
2. Mark Complete: Update status to [x], add #status-done.
3. File: Move the completed task file to the specific review folder (${ACA_DATA}/reviews/[author]/) to keep the inbox clean.

Checklist for Agents

• [ ] Is the document converted to MD?
• [ ] Do I understand exactly what the author wants help with?
• [ ] Have I created a Reading Guide that maps those questions to specific line numbers?
• [ ] Did I avoid offering my own critique unless explicitly asked?
• [ ] Is the final feedback drafted in the user's voice?