---
name: "document-harness"
description: "Use when creating, running, or updating the staged Markdown document-writing Harness from docs/PRD.md through research notes, drafts, feedback gates, and final documents."
---

# Document Harness Skill

Use this skill to turn `docs/PRD.md` into researched, reviewable, and feedback-driven Markdown documents.

## Operating Rules

1. Read `AGENTS.md`, `docs/PRD.md`, `docs/ARCHITECTURE.md`, `docs/ADR.md`, and `docs/UI_GUIDE.md` before planning document work.
2. Treat `docs/PRD.md` as the single source of requirements.
3. If PRD purpose, target reader, final deliverables, scope, or key questions are materially empty, stop and ask the user to complete PRD first.
4. Use `docs/ResearchNote.md` as the evidence ledger before drafting externally factual content.
5. Store review drafts under `drafts/` and final deliverables under `final/`.
6. Preserve `docs/DraftFeedback.md` and `docs/FinalFeedback.md`; never delete user feedback.
7. Run `python scripts/validate_docs.py` before reporting completion.

## Staged Workflow

### 1. PRD Intake

Read `docs/PRD.md` and identify:

- document purpose
- target readers
- final deliverables
- required outline
- important keywords
- key questions
- scope boundaries
- tone and style constraints
- research requirements

### 2. Rule Synthesis

Update only the relevant project-specific guidance in `AGENTS.md`.

Include:

- document purpose and target readers
- final deliverables
- tone and style rules
- citation and verification standards
- draft and final feedback process

Keep the generic Codex configuration and repository workflow concise.

### 3. Research Note

Research PRD keywords and key questions. Prefer official, academic, government, institutional, or other primary sources.

Write `docs/ResearchNote.md` with:

- search date
- search terms
- source URLs
- source quality notes
- core findings
- conflicting claims
- unresolved questions
- intended document usage

Use `doc_researcher` or `evidence_checker` agents when the user or current phase explicitly asks for subagent work.

### 4. Draft Documents

Create all PRD deliverables under `drafts/`.

Drafts must:

- answer the PRD key questions
- stay inside PRD scope
- use the requested tone
- link factual claims to `docs/ResearchNote.md`
- mark weak or missing evidence

After drafting, request user review in `docs/DraftFeedback.md`.

### 5. Draft Feedback Gate

If `docs/DraftFeedback.md` has no actionable user feedback or approval, mark the phase step as `blocked` with a clear `blocked_reason`.

If feedback exists, summarize it before revising.

### 6. Final Documents

Create final deliverables under `final/`. Do not overwrite `drafts/`.

Final documents must reflect:

- PRD requirements
- ResearchNote evidence
- DraftFeedback requests
- UI guide style rules

After finalizing, request user review or approval in `docs/FinalFeedback.md`.

### 7. Final Feedback Gate

If `docs/FinalFeedback.md` does not contain approval or actionable next feedback, mark the phase step as `blocked`.

If approval exists, mark the phase completed.

## Phase Files

When creating a new phase, use `references/phase-templates.md`.

Each step must include:

- files to read
- exact task
- acceptance criteria
- validation procedure
- status update instructions
- concrete forbidden actions

## Validation

Always run:

```bash
python scripts/validate_docs.py
```

For executor changes, also run:

```bash
python -m pytest scripts/test_execute.py
```