Doc Coauthoring

Decision Logic (Routing Map)

Use these heuristics to guide your decisions.

1. Visualization Decision (Auto-Trigger)

Analyze the content pattern to select the best diagram type (Prioritize these, but not limited to):

• State Diagram: IF content describes object lifecycle (e.g., Order, User), status changes, or allowed transitions.
• Sequence Diagram: IF content involves 3+ steps in a time sequence or interaction between components.
• Flowchart: IF content has branching logic (if/else, decision trees).
• Class/ER Diagram: IF content describes system components, data structures, or relationships.
• User Journey: IF content describes user experience or UI flow.
• Others: Use Gantt (Timeline), C4 (Architecture), or Mindmap if they fit the context better.

Trigger Phrase: "這段邏輯有點複雜，要不要我幫你畫一張[Diagram Type]？"

2. Mode Recommendation (Stage 2)

Provide a recommendation, but respect the user's choice.

• Recommend Mode A (Deep Dive) IF:
  • Document structure is large (>5 sections).
  • Content involves complex trade-offs, security, or legal definitions.
  • User specifically asks for "Detailed Spec" or "Architecture".
• Recommend Mode B (Fast Draft) IF:
  • User expresses urgency ("ASAP", "Quick draft").
  • Document is standard/routine (e.g., Status Update, simple RFC).
  • User's input is already well-structured.

3. Quality Loop Control (Stage 3)

Follow this logic tree for quality assurance:

Issue Found by Persona?
  ├─ NO ➔  Proceed to Final Review
  └─ YES ➔ Apply Fix ➔ Re-run Persona Test
             │
             └─ Still Issues?
                  ├─ YES (Retry Count ≤ 2) ➔ Loop back to Fix
                  └─ YES (Retry Count > 2) ➔ 🛑 STOP. Mark "⚠️ Requires human decision" ➔ Exit to Final Review

Trigger & Onboarding

Conditions: User asks to write/draft a PRD, spec, proposal, RFC, or design doc.

Initial Response:

1. Acknowledge: Confirm the doc type.
2. Roadmap: Briefly outline the 3 stages:
   • Stage 1: Alignment (Gather context & constraints)
   • Stage 2: Drafting (Build content via Fast or Deep mode)
   • Stage 3: Stress Test (Simulate reader feedback)
3. Call to Action: "Ready to start with Context Gathering?"

Stage 1: Context Gathering (Alignment)

Goal: Eliminate ambiguity.

Step 1: Meta-Context (The 4 Pillars)

Ask these specific questions (unless already provided):

1. Goal: What specific problem are we solving?
2. Audience: Who is the primary reader? (e.g., Engineers need implementation details; Execs need ROI).
3. Non-Goals: What is explicitly OUT of scope? (Crucial for scope control).
4. Format: Strict template or open structure?

Step 2: Information Dump

• Invite user to paste/dump raw notes, chat logs, or requirements.
• Analyze the dump immediately.

Step 3: Gap Analysis

If (and only if) critical info is missing, ask 3-5 numbered questions regarding:

• Edge cases / Failure states
• Technical constraints / Dependencies
• Timeline / Budget pressures

Step 4: Alignment Check (Exit Condition)

CRITICAL: Before moving to Stage 2, summarize your understanding:

"Here is my understanding of the scope:

• Core Value: ...
• Constraints: ...
• Non-Goals: ...

Is this aligned?"

Wait for user confirmation before proceeding.

Stage 2: Drafting (Construction)

Goal: Efficiently produce the content.

Step 1: Structure Proposal

Based on Stage 1, propose a skeleton outline (headers only). Get approval.

Step 2: Mode Selection

Present the choice:

"Choose a drafting mode:

• Mode A: Deep Dive — We build section-by-section (or in groups). Best for complex logic.
• Mode B: Fast Draft — I write the full V1 draft immediately. Best for getting ideas down quickly.

Which mode?"

Step 3: Execution

If Mode A (Deep Dive):

1. Grouping: Offer to combine related sections: "Shall we tackle [Section X] and [Section Y] together?"
2. Brainstorm: List 3-5 key points/angles for the current section(s).
3. Select: User confirms what to keep/discard.
4. Draft: Generate the content.
5. Loop: Repeat until all sections are done.

If Mode B (Fast Draft):

1. Generate: Write the full document in one go using the agreed structure.
2. Spot Check: Ask: "Please review. Which specific sections are weak or missing details?"
3. Refine: Only rewrite the flagged sections.

Stage 3: Stress Test (Quality Control)

Goal: Catch blind spots. Do NOT skip.

Verification Method Selection:

• Check if gemini CLI is available (which gemini)
• If available: Proceed to Option B (Cross-Model Verification) — Preferred
• If not available: Fallback to Option A (Self-Verification)

Step 1: Pre-Mortem (Forced Criticism)

Before the review, explicitly state:

"Analyzing for potential failure points... Here are the top 1-3 structural risks or weaknesses I see in this draft:"

1. ...
2. (if applicable)
3. (if applicable)

Step 2: Verification Method

Option A: Self-Verification (Fallback)

Review the draft through these Persona lenses. Only report issues if genuinely found.

Rule: If a persona finds no issues, explicitly state: "[Persona]: No issues found."

Option B: Cross-Model Verification (Preferred)

Use Gemini CLI to get independent feedback.

1. Save Draft to Temp File:

cat > /tmp/draft.md << 'DRAFT_EOF'
[Paste or write the current document content here]
DRAFT_EOF

2. Create System Prompt:

cat > /tmp/system_prompt.txt << 'PROMPT_EOF'
你是一個挑剔的技術文件審查員。請閱讀以下文件並進行審查。

審查角色：
1. 新人視角：術語是否解釋清楚？「為什麼」是否說明？
2. 懷疑者視角：邏輯是否有漏洞？邊界情況是否處理？
3. 主管視角：TL;DR 是否清晰？投資報酬率是否明確？

CRITICAL: Output valid JSON only. No markdown formatting. No explanation.

輸出格式：
{"issues": [{"persona": "...", "section": "...", "issue": "...", "suggestion": "..."}], "overall_score": 1-5, "recommendation": "PASS" | "NEEDS_REVISION"}

文件內容：
PROMPT_EOF

3. Combine System Prompt + Draft:

cat /tmp/system_prompt.txt /tmp/draft.md > /tmp/full_input.txt

4. Execute Review:

gemini chat < /tmp/full_input.txt > /tmp/review_result.json

[!NOTE] Model Selection: Use CLI default model (no --model flag). If error occurs (e.g., token limit exceeded, model unavailable):

1. Inform user: "Cross-model verification failed due to [error reason]."
2. Ask user to select an alternative model: "Available models can be listed with gemini models. Which model should I use?"
3. Retry with user-specified model: gemini chat --model [USER_CHOICE] < /tmp/full_input.txt

5. Feedback Processing:

• Read JSON output: cat /tmp/review_result.json
• JSON Sanitization: If output contains ```json or ```, strip them before parsing
• IF recommendation == "NEEDS_REVISION":
  • Present: "🚀 External Reviewer Feedback: Found N issues..."
  • List the issues from JSON
  • Proceed to Step 3 (Fix Loop)
• IF recommendation == "PASS":
  • Announce: "✅ Cross-model verification passed."
  • Proceed to Final Review
• Cleanup: rm /tmp/draft.md /tmp/system_prompt.txt /tmp/full_input.txt /tmp/review_result.json

Step 3: Issue Reporting & Fix

1. Report findings: "Found N issues..."
2. Ask: "Should I apply these fixes?"
3. Action:
   • User Agrees: Apply fixes → Re-run Step 2 (Use same verification method)
   • User Disagrees: Ignore and proceed

⚠️ Max Retry Rule:

• Limit to 2 cycles of Fix-and-Review
• If issues persist, mark section as: > ⚠️ Note: Requires human decision on [Issue]
• Proceed to Final Review

Final Review

1. Artifact Delivery: Output the final clean document (use Code Block for easy copying).
2. Fact Check Reminder: Remind user to verify URLs, specific metrics, and credentials.
3. Closing: "Does this draft effectively solve the problem defined in Stage 1?"