name: human_polish_brief
description: "Produces a targeted human polish brief for a chapter that requires voice correction, style diversity improvement, or AI-fingerprint reduction."
debug: false
model: power
system: agent_prompt
agent_prompt:
  - "= identity.md"
sections:
  - agent
  - project
  - deliverables
  - rag
  - message
  - instructions
steps:
  # Step 0: load the chapter content
  - type: tool
    action: git_read_file
    optional: false
    output_key: chapter_text
    params:
      path: "staging/draft/{chapter.slug}.md"

  # Step 1: load the slop gate flag report if available
  - type: tool
    action: git_read_file
    optional: true
    output_key: slop_gate_report
    params:
      path: "staging/flags/slop_gate_flag_{task.parent_id}.md"

  # Step 2: load voice signature for comparison
  - type: tool
    action: git_read_file
    optional: true
    output_key: voice_signature
    params:
      path: "agents/{agent.name}/voice_signature.json"

  # Step 3: load the chapter outline for this chapter
  - type: tool
    action: git_read_file
    optional: true
    output_key: chapter_brief
    params:
      path: "staging/briefs/brief-{chapter.slug}.md"

  # Step 4: produce the full human polish brief
  - type: think
    max_tokens: 3000
    output_key: polish_brief
    hint: |
      You are {agent.name}, producing a Human Polish Brief for {project.name}.
      The brief tells a human editor exactly what to fix in this chapter and why.

      Chapter content: the DELIVERABLES section above.
      Slop gate report: {slop_gate_report}
      Author voice signature: {voice_signature}
      Chapter brief / outline: {chapter_brief}

      Structure your brief as follows:

      ## Human Polish Brief -- {chapter.slug}

      ### Why This Chapter Needs Human Revision
      [2-3 sentences: what triggered this brief. Be specific. Cite gate scores if available.]

      ### Priority Revision Targets
      [4-8 numbered items. For each:]
      - LOCATION: paragraph N or approximate position in chapter
      - QUOTE: the exact passage (1-3 sentences) that needs revision
      - PROBLEM: what makes this feel AI-generated or voice-wrong
      - DIRECTION: what the human should do instead (specific, not vague)

      ### Voice Calibration Notes
      [3-5 bullet points on what authentic voice for this author and project sounds like.
       If voice_signature is available, reference the pacing_profile and register.
       If not available, derive from the project genre and character context.]

      ### Sentence Architecture Guidance
      [Specific advice on sentence length variety, opening word variety, paragraph rhythm.
       Target: at least 3 different sentence lengths per paragraph, no two consecutive
       paragraphs opening with the same grammatical structure.]

      ### Style Diversity Targets
      [Specific patterns to break: list the repeated constructions found in this chapter
       (e.g., "5 of 12 paragraphs begin with 'She'") and alternatives.]

      ### Acceptance Criteria
      The revised chapter should:
      - Achieve AI fingerprint score < 50 on re-check
      - Show sentence length variance > 8.0
      - Have opening word repetition rate < 0.25
      - Preserve all plot beats and character beats from the chapter brief
      - Maintain the genre and audience register

      Output ONLY the brief text above. No preamble.

  # Step 5: write brief to deliverables
  - type: document
    source_step: polish_brief
    filename: "human_polish_brief_{chapter.slug}"
    dest_path: "staging/flags"
    commit_msg: "brief: human polish brief for {chapter.slug} -- task {task.id}"

  # Step 6: reply to channel
  - type: reply
    target: channel
    channel_name: "crimson_leaf_publishing:live-feed"
    hint: |
      Post: "Human Polish Brief ready for {chapter.slug}. Saved to staging/flags/.
      Assign to a human editor or David for manual revision before re-running the slop gate."

adjudication:
  enabled: true
  pass_threshold: 65
  deliverable_type: brief
  criteria:
    specificity:
      weight: 40
      description: "Revision targets quote actual text and give specific direction"
    completeness:
      weight: 35
      description: "All required sections present with meaningful content"
    actionability:
      weight: 25
      description: "A human editor can follow the brief without additional context"