NINI
132 lines
3.4 KiB
Markdown
132 lines
3.4 KiB
Markdown
---
|
|
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
|
|
```
|