Agentic-AI-Template/Writing/Codex/.agents/skills/document-harness/SKILL.md

name, description

name	description
document-harness	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:

python scripts/validate_docs.py

For executor changes, also run:

python -m pytest scripts/test_execute.py