analysis-revision

/analysis-revision — Structured Review Revision

Guides the user through a structured revision workflow for an analysis design that has received review comments. Reads review feedback via MCP, creates a persistent tracking file for per-comment progress, and helps address each comment through interactive dialogue.

When to Use

• Design status is revision_requested and review comments need to be addressed
• Resuming a previously interrupted revision session
• Systematically working through all reviewer feedback before re-submitting

When NOT to Use

• Creating a new design from scratch (-> /analysis-design)
• Recording reasoning during active analysis (-> /analysis-journal)
• Structured reflection and conclusion (-> /analysis-reflection)
• Design is not in revision_requested status

Workflow

Phase 1: Situation Assessment

1. If $ARGUMENTS contains a design ID (e.g., "FP-H01"), use it directly. Otherwise, call list_analysis_designs(status="revision_requested") and ask the user to select.

2. get_analysis_design(design_id) -- load the design.

3. Status check: If status != "revision_requested", display an error and exit:

   このデザイン ({design_id}) は revision_requested 状態ではない (現在: {status})。
   レビューで修正依頼が出た後にこのスキルを使おう。
   

4. get_review_comments(design_id) -- get all review batches.

5. Batch selection (important -- do NOT just pick the newest batch overall):

   • Filter the returned batches to only those where status_after == "revision_requested"
   • From the filtered set, pick the one with the newest created_at
   • This is the target batch for this revision session

6. If no qualifying batch found (all batches have status_after != "revision_requested"):

   revision_requested に対応するレビューバッチが見つからない。
   レビューが WebUI 経由で提出されているか確認しよう。
   

   Exit.

7. Display situation summary:

   -- Revision: {design_id} --
   Title: {title}
   Status: {status}
   Target batch: {batch.id} ({batch.created_at})
   Reviewer: {batch.reviewer}
   Comments: {len(batch.comments)} items
   

Phase 2: Tracking Initialization

1. Read .insight/designs/{design_id}_revision.yaml using the Read tool.

2. If file exists AND batch_id matches the target batch -> reuse existing tracking (session resume). Show: "前回のセッションから再開する。未対応のコメントから進めよう。"

3. If file does not exist OR batch_id does not match the target batch -> create new tracking file.

4. If file exists but is corrupted (parse error) -> treat as non-existent and create new tracking file. Show: "tracking file が破損していたため、新しいバッチから再作成する。"

New tracking file schema:

batch_id: "{target_batch.id}"
created_at: "{now_jst in ISO 8601 format}"
items:
  - index: 0
    fingerprint: "{fingerprint}"
    comment_summary: "{first 50 chars of comment}"
    target_section: "{target_section or null}"
    status: "open"
    addressed_at: null
  - index: 1
    fingerprint: "{fingerprint}"
    comment_summary: "{first 50 chars of comment}"
    target_section: "{target_section or null}"
    status: "open"
    addressed_at: null
  # ... one item per comment in the batch

Fingerprint generation formula (stable identity key for cross-session matching):

import hashlib
fingerprint = hashlib.sha256(f"{comment}|{target_section or ''}".encode()).hexdigest()[:8]

The fingerprint is based on comment content rather than index position, so it remains stable even if comments are reordered. It is used for reconciliation when resuming a session.

Write the tracking file using the Write tool. Write the full YAML content to .insight/designs/{design_id}_revision.yaml.

Note: In production code, atomic writes should use the tempfile + os.replace() pattern. Since the skill operates through Claude's Write tool, the tool handles file writing directly.

Phase 3: Comment Addressing Loop

For each item in the tracking file where status == "open":

1. Display the comment with context:

   -- Comment {index+1}/{total} --
   Section: {target_section or "general"}
   Comment: {full comment text from the batch}
   Target content: {target_content from the batch, if present}
   Current value: {current value of that section from get_analysis_design, if target_section is set}
   Status: {status}
   

   To get the current value, call get_analysis_design(design_id) and extract the field matching target_section (e.g., if target_section == "hypothesis_statement", show design.hypothesis_statement).

2. Ask user for direction:

   どう対応する？
   1. fix -- 修正する (修正内容を一緒に考える)
   2. skip -- 対応しない (wontfix としてマーク)
   3. discuss -- 方針を相談したい
   

3. If fix:

   • Discuss the fix with the user
   • Apply the change via update_analysis_design(design_id, **changes)
   • Update tracking item: status: "addressed", addressed_at: "{now_jst}"

4. If skip (wontfix):

   • Confirm with user: "このコメントを wontfix にする。理由を一言で?"
   • Update tracking item: status: "wontfix", addressed_at: "{now_jst}"

5. If discuss:

   • Engage in discussion about the comment
   • After discussion, return to the direction choice (fix / skip)

6. Write updated tracking file after each comment is resolved. Write the full YAML content to .insight/designs/{design_id}_revision.yaml using the Write tool.

Phase 4: Completion Check

1. After all items have been processed, verify: every item has status of either "addressed" or "wontfix".

2. Show summary:

   -- Revision Summary --
   Total: {total} comments
   Addressed: {addressed_count}
   Won't fix: {wontfix_count}
   

3. Propose re-submission:

   全コメントへの対応が完了した。in_review に戻してレビュアーに再確認を依頼する？
   

   If yes: transition_design_status(design_id, "in_review")

4. Suggest next steps:

   • "大きな方針変更が必要なら /analysis-design {design_id} で再設計"
   • "調査してから修正したい場合は /analysis-journal {design_id} で記録しながら進めよう"
   • "in_review に戻した後、レビュアーは WebUI で再レビューできる"

MCP Tool Reference

Tool	Used for
get_analysis_design(design_id)	Load design details and check status
list_analysis_designs(status?)	Find designs in revision_requested status
get_review_comments(design_id)	Get review batches with comments
update_analysis_design(design_id, ...)	Apply fixes to design fields
transition_design_status(design_id, new_status)	Re-submit for review (-> in_review)

Tracking File Location

.insight/designs/{design_id}_revision.yaml

This file is skill-managed data, not MCP-managed (see YAML Format Reference in analysis-design SKILL.md).

Error Handling

Situation	Action
Design not found	Show error, suggest list_analysis_designs()
Design not in revision_requested status	Show current status, exit with guidance
No revision_requested batch found	Show message, suggest checking WebUI review
Tracking file corrupted	Re-create from target batch, warn user
update_analysis_design fails	Show error, ask user to retry or adjust
Session interrupted mid-loop	On next run, resume from tracking file (open items)

Chaining

From	To	When
WebUI review (revision_requested)	-> /analysis-revision	Review submitted with revision_requested status
/analysis-revision	-> /analysis-design	Major redesign needed: "大きな方針変更が必要なら /analysis-design {id}"
/analysis-revision	-> /analysis-journal	Need to investigate before fixing: "調査してから修正するなら /analysis-journal {id}"
/analysis-revision	-> (WebUI review)	After transition to in_review, reviewer re-reviews in WebUI

Language Rules

• Follow project CLAUDE.md language settings. Default to Japanese if no setting.
• Code, IDs, tool names, and YAML fields always stay in English.
• Revision workflow guidance follows the user's language (usually Japanese).