Claude-Code-Workflow/.claude/skills/software-manual/phases/06-iterative-refinement.md

Phase 6: Iterative Refinement

Preview, collect feedback, and iterate until quality meets standards.

Objective

• Preview generated HTML in browser
• Collect user feedback
• Address issues iteratively
• Finalize documentation

Execution Steps

Step 1: Preview HTML

const buildReport = JSON.parse(Read(`${workDir}/build-report.json`));
const outputFile = `${workDir}/${buildReport.output}`;

// Open in default browser for preview
Bash({ command: `start "${outputFile}"` });  // Windows
// Bash({ command: `open "${outputFile}"` });  // macOS

// Report to user
console.log(`
📖 Manual Preview

File: ${buildReport.output}
Size: ${buildReport.size_human}
Sections: ${buildReport.sections}
Screenshots: ${buildReport.screenshots}

Please review the manual in your browser.
`);

Step 2: Collect Feedback

const feedback = await AskUserQuestion({
  questions: [
    {
      question: "How does the manual look overall?",
      header: "Overall",
      options: [
        { label: "Looks great!", description: "Ready to finalize" },
        { label: "Minor issues", description: "Small tweaks needed" },
        { label: "Major issues", description: "Significant changes required" },
        { label: "Missing content", description: "Need to add more sections" }
      ],
      multiSelect: false
    },
    {
      question: "Which aspects need improvement? (Select all that apply)",
      header: "Improvements",
      options: [
        { label: "Content accuracy", description: "Fix incorrect information" },
        { label: "More examples", description: "Add more code examples" },
        { label: "Better screenshots", description: "Retake or add screenshots" },
        { label: "Styling/Layout", description: "Improve visual appearance" }
      ],
      multiSelect: true
    }
  ]
});

Step 3: Address Feedback

Based on feedback, take appropriate action:

Minor Issues

if (feedback.overall === "Minor issues") {
  // Prompt for specific changes
  const details = await AskUserQuestion({
    questions: [{
      question: "What specific changes are needed?",
      header: "Details",
      options: [
        { label: "Typo fixes", description: "Fix spelling/grammar" },
        { label: "Reorder sections", description: "Change section order" },
        { label: "Update content", description: "Modify existing text" },
        { label: "Custom changes", description: "I'll describe the changes" }
      ],
      multiSelect: true
    }]
  });

  // Apply changes based on user input
  applyMinorChanges(details);
}

Major Issues

if (feedback.overall === "Major issues") {
  // Return to relevant phase
  console.log(`
  Major issues require returning to an earlier phase:

  - Content issues → Phase 3 (Parallel Analysis)
  - Screenshot issues → Phase 4 (Screenshot Capture)
  - Structure issues → Phase 2 (Project Exploration)

  Which phase should we return to?
  `);

  const phase = await selectPhase();
  return { action: 'restart', from_phase: phase };
}

Missing Content

if (feedback.overall === "Missing content") {
  // Identify missing sections
  const missing = await AskUserQuestion({
    questions: [{
      question: "What content is missing?",
      header: "Missing",
      options: [
        { label: "API endpoints", description: "More API documentation" },
        { label: "UI features", description: "Additional UI guides" },
        { label: "Examples", description: "More code examples" },
        { label: "Troubleshooting", description: "More FAQ items" }
      ],
      multiSelect: true
    }]
  });

  // Run additional agent(s) for missing content
  await runSupplementaryAgents(missing);
}

Step 4: Save Iteration

// Save current version before changes
const iterationNum = getNextIterationNumber(workDir);
const iterationDir = `${workDir}/iterations`;

// Copy current version
Bash({ command: `copy "${outputFile}" "${iterationDir}\\v${iterationNum}.html"` });

// Log iteration
const iterationLog = {
  version: iterationNum,
  timestamp: new Date().toISOString(),
  feedback: feedback,
  changes: appliedChanges
};

Write(`${iterationDir}/iteration-${iterationNum}.json`, JSON.stringify(iterationLog, null, 2));

Step 5: Regenerate if Needed

if (changesApplied) {
  // Re-run HTML assembly with updated sections
  await runPhase('05-html-assembly');

  // Open updated preview
  Bash({ command: `start "${outputFile}"` });
}

Step 6: Finalize

When user approves:

if (feedback.overall === "Looks great!") {
  // Final quality check
  const finalReport = {
    ...buildReport,
    iterations: iterationNum,
    finalized_at: new Date().toISOString(),
    quality_score: calculateFinalQuality()
  };

  Write(`${workDir}/final-report.json`, JSON.stringify(finalReport, null, 2));

  // Suggest final location
  console.log(`
  ✅ Manual Finalized!

  Output: ${buildReport.output}
  Size: ${buildReport.size_human}
  Quality: ${finalReport.quality_score}%
  Iterations: ${iterationNum}

  Suggested actions:
  1. Copy to project root: copy "${outputFile}" "docs/"
  2. Add to version control
  3. Publish to documentation site
  `);

  return { status: 'completed', output: outputFile };
}

Iteration History

Each iteration is logged:

iterations/
├── v1.html                    # First version
├── iteration-1.json           # Feedback and changes
├── v2.html                    # After first iteration
├── iteration-2.json           # Feedback and changes
└── ...

Quality Metrics

Track improvement across iterations:

const qualityMetrics = {
  content_completeness: 0,   // All sections present
  screenshot_coverage: 0,     // Screenshots for all UI
  example_diversity: 0,       // Different difficulty levels
  search_accuracy: 0,         // Search returns relevant results
  user_satisfaction: 0        // Based on feedback
};

Exit Conditions

The refinement phase ends when:

1. User explicitly approves ("Looks great!")
2. Maximum iterations reached (configurable, default: 5)
3. Quality score exceeds threshold (default: 90%)

Output

• Final HTML: {软件名}-使用手册.html
• Final Report: final-report.json
• Iteration History: iterations/

Completion

When finalized, the skill is complete. Final output location:

.workflow/.scratchpad/manual-{timestamp}/
├── {软件名}-使用手册.html     ← Final deliverable
├── final-report.json
└── iterations/

Consider copying to a permanent location like docs/ or project root.