maestro-flow 0.5.31 → 0.5.33

package/.agents/skills/scholar-review/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: scholar-review
+description: Systematic academic paper review workflow covering self-review before submission and rebuttal writing after receiving reviewer feedback. Triggers on "review paper", "self-review", "write rebuttal", "respond to reviewers", "analyze review comments", "paper review".
+allowed-tools: read_file, write_file, edit_file, shell, find_files, search, web_fetch, web_search, ask_user, track_tasks
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Scholar Review
+
+A structured workflow for academic paper review and rebuttal. Covers two modes: (1) pre-submission self-review to identify and fix weaknesses before submitting, and (2) post-review rebuttal writing to respond professionally to reviewer feedback.
+
+## Pre-load (before execution)
+
+1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, read for project context
+2. **Specs**: `maestro spec load --category coding` — load coding conventions
+3. **Wiki knowledge**: `maestro search "academic writing research paper" --json` — top 5 entries as prior context
+4. All optional — proceed without if unavailable
+
+## Architecture Overview
+
+```
+                          scholar-review
+                               |
+                    [Preference Collection]
+                         /            \
+              Pre-Submission        Post-Review
+                   |              /     |      \
+            +-----------+   +--------+--------+---------+
+            | Phase 1   |   | Phase 2| Phase 3| Phase 4 |
+            | Self-     |   | Review | Response| Rebuttal|
+            | Review    |   | Analysis| Strategy| Writing|
+            +-----------+   +--------+--------+---------+
+                   |              \     |      /
+                   v               v    v    v
+            self-review-       rebuttal-response.md
+            report.md                  |
+                                       v
+                                 +-----------+
+                                 | Phase 5   |
+                                 | Revision  |
+                                 +-----------+
+                                       |
+                                       v
+                                 revised-paper
+```
+
+## Key Design Principles
+
+1. **Mode-driven execution**: Pre-submission triggers Phase 1 only; post-review triggers Phases 2-5 sequentially
+2. **Evidence-based review**: Every finding must reference specific sections, pages, or line numbers
+3. **Professional tone**: All rebuttal output follows academic tone guidelines (grateful, respectful, evidence-based)
+4. **Completeness**: Every reviewer comment must receive a response; no comment is skipped
+5. **Actionable output**: Each phase produces concrete artifacts, not abstract advice
+
+## Interactive Preference Collection
+
+Collect workflow preferences before dispatching to phases:
+
+```
+Ask the user:
+
+1. Review Stage:
+   - "Pre-submission self-review" → Execute Phase 1 only
+   - "Post-review rebuttal" → Execute Phases 2-5
+
+2. Paper Location:
+   - Path to paper file(s) or directory
+
+3. (If post-review) Reviewer Comments Location:
+   - Path to reviewer comments file(s)
+
+4. (If post-review) Target Venue:
+   - Conference/journal name (e.g., NeurIPS, ICML, ICLR, CVPR, ACL)
+   - "Other" with custom venue name
+
+5. Auto Mode:
+   - "Interactive (Recommended)" → Confirm at each phase transition
+   - "Auto" → Execute all applicable phases without confirmation
+
+Store as workflowPreferences:
+  - mode: "pre-submission" | "post-review"
+  - paperPath: string
+  - reviewCommentsPath: string (post-review only)
+  - targetVenue: string
+  - autoYes: boolean
+```
+
+## Execution Flow
+
+> **COMPACT DIRECTIVE**: Context compression MUST check track_tasks phase status.
+> The phase currently marked `in_progress` is the active execution phase -- preserve its FULL content.
+> Only compress phases marked `completed` or `pending`.
+
+### Pre-Submission Mode
+
+```
+Phase 1: Self-Review
+  Ref: phases/01-self-review.md
+  Input: paperPath, targetVenue
+  Output: self-review-report.md
+  track_tasks: Mark Phase 1 in_progress → completed
+```
+
+### Post-Review Mode
+
+```
+Phase 2: Review Analysis
+  Ref: phases/02-review-analysis.md
+  Input: reviewCommentsPath, paperPath
+  Output: review-analysis.md (classified comments with priorities)
+  track_tasks: Mark Phase 2 in_progress → completed
+
+Phase 3: Response Strategy
+  Ref: phases/03-response-strategy.md
+  Input: review-analysis.md, paperPath
+  Output: response-strategy.md (strategy per comment)
+  track_tasks: Mark Phase 3 in_progress → completed
+
+Phase 4: Rebuttal Writing
+  Ref: phases/04-rebuttal-writing.md
+  Input: response-strategy.md, paperPath, targetVenue
+  Output: rebuttal-response.md
+  track_tasks: Mark Phase 4 in_progress → completed
+
+Phase 5: Revision
+  Ref: phases/05-revision.md
+  Input: rebuttal-response.md, paperPath
+  Output: revision-plan.md, tracked changes list
+  track_tasks: Mark Phase 5 in_progress → completed
+```
+
+**Phase Reference Documents** (read on-demand when phase executes):
+
+| Phase | Document | Purpose | Compact |
+|-------|----------|---------|---------|
+| 1 | [phases/01-self-review.md](phases/01-self-review.md) | Pre-submission quality check | track_tasks driven |
+| 2 | [phases/02-review-analysis.md](phases/02-review-analysis.md) | Parse and classify reviewer comments | track_tasks driven |
+| 3 | [phases/03-response-strategy.md](phases/03-response-strategy.md) | Plan rebuttal strategy per comment | track_tasks driven + sentinel |
+| 4 | [phases/04-rebuttal-writing.md](phases/04-rebuttal-writing.md) | Write structured rebuttal document | track_tasks driven + sentinel |
+| 5 | [phases/05-revision.md](phases/05-revision.md) | Plan and track paper revisions | track_tasks driven |
+
+**Compact Rules**:
+1. **track_tasks `in_progress`** -> Preserve full content, do not compress
+2. **track_tasks `completed`** -> May compress to summary
+3. **Sentinel fallback** -> Phases marked with sentinel contain compact sentinels; if only sentinel remains without full Step protocol, immediately `read_file()` to recover
+
+## Core Rules
+
+1. **Read paper first**: Always read the full paper before any review or analysis
+2. **Classify before responding**: Never write rebuttals without completing review analysis and strategy
+3. **No skipped comments**: Every reviewer comment must have a response entry
+4. **Venue-aware tone**: Adjust strategy and emphasis based on target venue conventions
+5. **Preserve reviewer numbering**: Maintain original reviewer IDs and comment numbering throughout
+
+## Input Processing
+
+```
+User input → Structured format:
+
+PAPER: [path to paper files]
+MODE: [pre-submission | post-review]
+REVIEWS: [path to reviewer comments] (post-review only)
+VENUE: [target conference/journal]
+OUTPUT_DIR: [directory for generated documents]
+```
+
+## Data Flow
+
+```
+paperPath ──────────────────────────────────────────────────┐
+    │                                                        │
+    v                                                        │
+Phase 1: self-review-report.md                               │
+    (Pre-submission mode ends here)                          │
+                                                             │
+reviewCommentsPath ─── Phase 2: review-analysis.md ──────────┤
+                           │                                 │
+                           v                                 │
+                    Phase 3: response-strategy.md ───────────┤
+                           │                                 │
+                           v                                 │
+                    Phase 4: rebuttal-response.md ───────────┤
+                           │                                 │
+                           v                                 │
+                    Phase 5: revision-plan.md ────── paperPath
+```
+
+## track_tasks Pattern
+
+### Phase Attachment (entering phase)
+```
+track_tasks([
+  { id: "phase-N", task: "Phase N: [name]", status: "in_progress" },
+  { id: "phase-N-step-1", task: "  Step N.1: [name]", status: "pending" },
+  { id: "phase-N-step-2", task: "  Step N.2: [name]", status: "pending" }
+])
+```
+
+### Phase Collapse (exiting phase)
+```
+track_tasks([
+  { id: "phase-N", task: "Phase N: [name] -- Done", status: "completed" },
+  { id: "phase-N+1", task: "Phase N+1: [name]", status: "in_progress" }
+])
+```
+
+## Error Handling
+
+1. **Paper not found**: Ask user to confirm paper path, retry once
+2. **Reviews not parseable**: Ask user to reformat or paste reviews directly
+3. **Phase failure**: Log error, ask user whether to retry or skip to next phase
+4. **Venue unknown**: Fall back to generic academic review conventions
+
+## Coordinator Checklist
+
+### Before Each Phase
+- [ ] Confirm input files exist and are readable
+- [ ] track_tasks updated: current phase `in_progress`
+- [ ] Read phase document via `Ref:` marker
+
+### After Each Phase
+- [ ] Output file generated and saved
+- [ ] track_tasks updated: current phase `completed`
+- [ ] If not autoYes, confirm with user before next phase
+
+### Post-Workflow
+- [ ] All output files listed for user
+- [ ] Summary of findings/actions presented

package/.agents/skills/scholar-review/phases/01-self-review.md

@@ -0,0 +1,186 @@
+# Phase 1: Self-Review
+
+Conduct a comprehensive pre-submission quality review of the paper, identifying weaknesses and providing actionable improvement suggestions.
+
+## Objective
+
+- Systematically evaluate paper quality across structure, logic, citations, figures/tables, and writing
+- Identify issues before external reviewers find them
+- Generate a prioritized self-review report with concrete fixes
+
+## Execution
+
+### Step 1.1: Read and Understand the Paper
+
+Read the full paper to understand:
+- Research question and contributions
+- Methodology and experimental design
+- Results and conclusions
+- Target venue requirements (if known)
+
+```
+read_file(paperPath)
+```
+
+Store: `paperContent` (full paper text), `paperStructure` (section outline)
+
+### Step 1.2: Structure Review
+
+Check whether all sections are complete and conform to academic standards:
+
+**Checklist**:
+- [ ] Abstract includes: problem statement, method summary, key results, contributions
+- [ ] Introduction clearly articulates research motivation, background, and gap
+- [ ] Related Work covers key prior work and positions the contribution
+- [ ] Method section is detailed enough to be reproducible
+- [ ] Results sufficiently support the conclusions with appropriate evidence
+- [ ] Discussion addresses limitations, implications, and future work
+- [ ] Conclusion summarizes contributions without overclaiming
+
+**For each missing or weak element**, record:
+```
+{
+  section: "Section name",
+  issue: "Description of the problem",
+  severity: "critical | major | minor",
+  suggestion: "Specific improvement action"
+}
+```
+
+### Step 1.3: Logic Consistency Check
+
+Verify the logical coherence of the paper:
+
+- Do research questions align with the methodology?
+- Does the experimental design support the research hypotheses?
+- Are result interpretations reasonable and supported by data?
+- Are conclusions supported by the presented evidence?
+- Are there logical gaps or unsupported claims?
+
+**Technique**: Read from conclusion backwards to check logical coherence.
+
+For each inconsistency found:
+```
+{
+  location: "Section X.Y, paragraph Z",
+  type: "gap | unsupported_claim | contradiction | overclaim",
+  description: "What the issue is",
+  suggestion: "How to fix it"
+}
+```
+
+### Step 1.4: Citation Completeness
+
+Check citations for:
+- All in-text citations present in the reference list
+- Reference format consistency (all same style)
+- Key related works cited (search for obvious missing references)
+- Citations accurately reflect the original content (no misattributions)
+- Self-citations appropriate (not excessive, not missing key ones)
+
+### Step 1.5: Figure and Table Quality
+
+Evaluate every figure and table:
+- Clear, descriptive titles and captions
+- Readable at standard print size (font sizes, resolution)
+- Support the text narrative (referenced and discussed)
+- Format compliant with venue requirements
+- Consistent style across all figures/tables
+- Axes labeled, units specified, legends present
+
+### Step 1.6: Writing Clarity
+
+Assess writing quality:
+- Language is concise and clear (no unnecessary jargon)
+- Technical terminology used correctly and consistently
+- Sentence structures are clear (no run-on sentences, ambiguity)
+- Paragraph organization is logical (topic sentences, transitions)
+- No grammatical errors or typos
+- Consistent notation throughout
+
+### Step 1.7: Venue-Specific Check
+
+If target venue is known, check venue-specific requirements:
+
+**General conference checks**:
+- Page limit compliance
+- Required sections present (ethics statement, broader impact, reproducibility)
+- Anonymous submission requirements met
+- Supplementary material properly formatted
+
+**Venue-specific emphasis**:
+- NeurIPS: Conceptual novelty, broader impact, reproducibility checklist
+- ICML: Theoretical rigor, mathematical proofs, methodological contribution
+- ICLR: Experimental thoroughness, limitations discussion, LLM disclosure
+- CVPR: Visual quality, experimental completeness
+- ACL: Linguistic significance, ethics statement, limitations section
+
+### Step 1.8: Generate Self-Review Report
+
+Compile all findings into a structured report:
+
+```markdown
+# Self-Review Report
+
+## Paper: [Paper Title]
+## Date: [Date]
+## Target Venue: [Venue or "Not specified"]
+
+## Executive Summary
+
+[2-3 sentence overview of paper quality and main areas for improvement]
+
+## Critical Issues (Must Fix)
+
+### Issue 1: [Title]
+- **Location**: [Section, page, paragraph]
+- **Category**: [Structure | Logic | Citation | Figure | Writing | Venue]
+- **Description**: [What the problem is]
+- **Suggestion**: [Specific action to fix]
+
+[... more critical issues]
+
+## Major Issues (Should Fix)
+
+[Same format as critical]
+
+## Minor Issues (Nice to Fix)
+
+[Same format as critical]
+
+## Quality Checklist Summary
+
+| Category | Status | Notes |
+|----------|--------|-------|
+| Abstract completeness | Pass/Fail | ... |
+| Introduction clarity | Pass/Fail | ... |
+| Method reproducibility | Pass/Fail | ... |
+| Results support conclusions | Pass/Fail | ... |
+| Discussion addresses limitations | Pass/Fail | ... |
+| Figures/tables quality | Pass/Fail | ... |
+| Citations complete | Pass/Fail | ... |
+| Writing clarity | Pass/Fail | ... |
+| Venue requirements | Pass/Fail | ... |
+
+## Reviewer Perspective
+
+[Brief simulation of likely reviewer concerns -- what would reviewers
+likely focus on? What questions would they ask?]
+
+## Recommended Priority Actions
+
+1. [Most important fix]
+2. [Second most important]
+3. [Third most important]
+```
+
+Save to: `{OUTPUT_DIR}/self-review-report.md`
+
+## Output
+
+- **File**: `self-review-report.md` in the designated output directory
+- **track_tasks**: Mark Phase 1 completed
+
+## Next Phase
+
+For pre-submission mode, the workflow ends here. Return to orchestrator with self-review report location.

package/.agents/skills/scholar-review/phases/02-review-analysis.md

@@ -0,0 +1,203 @@
+# Phase 2: Review Analysis
+
+Parse, classify, and prioritize all reviewer comments to create a structured analysis that drives the response strategy.
+
+## Objective
+
+- Parse reviewer comments into individual addressable items
+- Classify each comment by type (Major / Minor / Typo / Misunderstanding)
+- Assign priority based on impact on acceptance decision
+- Map comments to paper sections for targeted responses
+
+## Execution
+
+### Step 2.1: Read Reviewer Comments
+
+Read all reviewer feedback files:
+
+```
+read_file(reviewCommentsPath)
+```
+
+Also re-read the paper for cross-referencing:
+```
+read_file(paperPath)
+```
+
+Identify reviewer structure:
+- Number of reviewers
+- Review format (structured with scores, free-form, or mixed)
+- Overall scores/recommendations if present
+
+### Step 2.2: Parse Comments into Individual Items
+
+Break each reviewer's feedback into discrete, addressable comments. For each comment extract:
+
+```
+{
+  reviewerId: "Reviewer 1" (preserve original numbering),
+  commentId: "1.1" (reviewer.sequence),
+  originalText: "Exact quote of the comment",
+  paperSection: "Section the comment refers to",
+  summary: "One-line summary of what the reviewer wants"
+}
+```
+
+**Parsing rules**:
+- One concern = one comment item, even if the reviewer wrote them together
+- Preserve exact reviewer wording in `originalText`
+- If a reviewer lists multiple points in one paragraph, split them
+- Capture both explicit requests and implicit concerns
+
+### Step 2.3: Classify Each Comment
+
+Apply the four-category classification system:
+
+**Major Issues**:
+- Questions research method validity
+- Requests additional experiments or comparisons
+- Challenges result interpretation logic
+- Questions novelty or contribution significance
+- Keywords: "major concern", "fundamental issue", "missing experiments", "insufficient evidence", "not convincing"
+
+**Minor Issues**:
+- Requests clarification of details
+- Suggests presentation improvements
+- Asks for additional related work discussion
+- Suggests figure/table improvements
+- Keywords: "minor concern", "could be improved", "please clarify", "suggestion", "it would be better"
+
+**Typos/Formatting**:
+- Spelling errors
+- Grammar issues
+- Reference format inconsistencies
+- Figure/table labeling errors
+- Keywords: "typo", "grammar", "formatting", "inconsistent"
+
+**Misunderstandings**:
+- Reviewer misread or missed existing content
+- Reviewer confused concepts the paper already addresses
+- Reviewer asks for something already present
+- Keywords: "The authors did not..." (but they did), "It is unclear..." (but it is stated)
+
+### Step 2.4: Prioritize Comments
+
+Assign priority to each classified comment:
+
+**Priority order**:
+1. **Critical** -- Major Issues that could cause rejection (address first)
+2. **High** -- Misunderstandings that could worsen if not clarified
+3. **Medium** -- Minor Issues that improve paper quality
+4. **Low** -- Typos and formatting (straightforward fixes)
+
+**Cross-reviewer analysis**:
+- Flag comments raised by multiple reviewers (higher priority)
+- Note contradictory comments between reviewers
+- Identify "champion" reviewer (most positive) vs skeptical reviewer
+
+### Step 2.5: Map to Paper Sections
+
+For each comment, identify the exact paper location it refers to:
+
+```
+{
+  commentId: "1.1",
+  paperLocation: {
+    section: "Section 3.2",
+    page: "5",
+    paragraph: "2",
+    element: "Equation 3" | "Figure 2" | "Table 1" | null
+  },
+  existingContent: "Brief quote of relevant existing paper content" | null
+}
+```
+
+This mapping enables:
+- Quick reference when writing responses
+- Identifying if the paper already addresses the concern
+- Planning targeted revisions
+
+### Step 2.6: Generate Review Analysis Document
+
+Compile the analysis into a structured document:
+
+```markdown
+# Review Analysis
+
+## Paper: [Paper Title]
+## Date: [Date]
+## Reviewers: [N] reviewers
+
+## Overall Assessment
+
+| Reviewer | Score | Recommendation | Stance |
+|----------|-------|----------------|--------|
+| Reviewer 1 | [score] | [accept/reject/revise] | [champion/neutral/skeptical] |
+| Reviewer 2 | [score] | [accept/reject/revise] | [champion/neutral/skeptical] |
+| ... | | | |
+
+**Consensus areas**: [What reviewers agree on]
+**Disagreement areas**: [Where reviewers disagree]
+
+## Comment Summary by Category
+
+| Category | Count | Reviewers |
+|----------|-------|-----------|
+| Major Issues | N | R1, R2 |
+| Minor Issues | N | R1, R2, R3 |
+| Typos/Formatting | N | R1, R3 |
+| Misunderstandings | N | R2 |
+
+## Detailed Comment Analysis
+
+### Critical Priority
+
+#### Comment 1.1 [Major] (Reviewer 1)
+- **Original**: "[exact quote]"
+- **Summary**: [one-line summary]
+- **Paper Location**: Section X.Y, page Z
+- **Existing Content**: [relevant quote from paper, or "Not addressed"]
+- **Cross-reviewer**: [Also raised by Reviewer N] | [Unique to this reviewer]
+
+[... more critical comments]
+
+### High Priority
+
+[Same format]
+
+### Medium Priority
+
+[Same format]
+
+### Low Priority
+
+[Same format]
+
+## Cross-Reviewer Patterns
+
+### Comments Raised by Multiple Reviewers
+- [Topic]: Reviewers [X, Y] -- [summary]
+
+### Contradictory Comments
+- Reviewer X says [A], Reviewer Y says [B] -- [analysis]
+
+## Key Statistics
+
+- Total comments: N
+- Major: N (X%)
+- Minor: N (X%)
+- Typo: N (X%)
+- Misunderstanding: N (X%)
+```
+
+Save to: `{OUTPUT_DIR}/review-analysis.md`
+
+## Output
+
+- **File**: `review-analysis.md` in the designated output directory
+- **Variable**: `reviewAnalysis` (parsed comment data for Phase 3)
+- **track_tasks**: Mark Phase 2 completed, Phase 3 in_progress
+
+## Next Phase
+
+Return to orchestrator, then auto-continue to [Phase 3: Response Strategy](03-response-strategy.md).