Doc Writing

Doc Writing (HWPR/AWOR)

In the AI era, human value judgments get buried in AI-expanded long documents. This skill uses HWPR/AWOR markers so readers (human or AI) can quickly locate what the human actually thought.

For the detailed template, see [examples/TEMPLATE-HWPR.md](examples/TEMPLATE-HWPR.md).

---

Core Concepts

• [HWPR] (Human Wrote, Please Read): Unknown context + value judgments written by a human. Must be short (3-5 sentences).
• [AWOR] (AI Wrote, Optional Read): Detailed content expanded by AI. Can be deleted, modified, or replaced.

---

Rules

1. Never modify [HWPR] content — AI may only read HWPR paragraphs; it must not rewrite, rephrase, merge, or "polish" them
2. HWPR must be short — Each HWPR paragraph must not exceed 3-5 sentences; write only: unknown context + value judgments
3. Value judgments with humility — Use phrasing like "I believe" / "current judgment" / "possibly" in HWPR, acknowledging potential error
4. [AWOR] can be freely modified — AI-expanded content may be replaced, deleted, or rewritten at any time
5. Consistent marker format — Use bold markers **[HWPR]** and **[AWOR]** as headers, followed by paragraph titles
6. HWPR uses blockquote — HWPR body text uses > block quotes for visual distinction

---

Execution Flow

Mode A: Write a New Document

Trigger Conditions

User requests "help me write a document," "write a proposal," "draft a PRD," etc.

Step 1: Guide HWPR Extraction

Ask the user questions to extract core value judgments:

To write an effective document, I need you to provide the following HWPR content (keep it brief, 1-3 sentences per item):

1. **Background**: Why are we doing this? What is the core problem?
2. **Judgment**: What do you think we should do? Why this direction?
3. **Trade-offs**: What was deliberately given up? What are the known risks?

Step 2: Confirm HWPR

Organize the user's answers into HWPR paragraphs and display them for user confirmation. Once confirmed, HWPR is never modified afterwards.

Step 3: Generate Complete Document

Following the [TEMPLATE-HWPR.md](examples/TEMPLATE-HWPR.md) structure, expand corresponding AWOR paragraphs after each HWPR paragraph.

---

Mode B: Rewrite an Existing Document

Trigger Conditions

User provides an existing document and requests "restructure using HWPR/AWOR," "split and label," etc.

Step 1: Identify Potential HWPR

Read the full text and mark sentences/paragraphs that appear to contain human value judgments (identification criteria: contains subjective decisions, trade-offs, "we chose" / "gave up" language, etc.).

Step 2: Confirm with User

List the identified results and ask the user to confirm each one:

I identified the following as potentially your value judgments (HWPR) in the document. Please confirm:

1. yes/no "We chose option B because..." (paragraph X)
2. yes/no "Abandoned real-time push, switched to polling..." (paragraph Y)
3. yes/no ...

Step 3: Split, Label + Expand

Extract confirmed HWPR into **[HWPR]** paragraphs, mark remaining content as **[AWOR]**, and expand where necessary.

---

Mode C: Review a Document

Trigger Conditions

User requests "review the document," "check HWPR formatting," etc.

Review Checklist

Check and report the following issues:

| Check Item | Issue Description | |--------|---------| | Missing markers | Paragraph has no [HWPR] or [AWOR] marker | | HWPR too long | HWPR paragraph exceeds 5 sentences | | HWPR contains AI style | HWPR has obvious AI-expansion artifacts (boilerplate, "in summary," etc.) | | AWOR contains value judgments | AWOR contains "we decided" / "gave up" etc. that should be HWPR content | | Incorrect marker format | Not using the standard **[HWPR]** / **[AWOR]** format |

Output format: List each issue + suggested fix.

---

Examples

Bad — HWPR too long, mixed with AI style

**[HWPR]** Background and Judgment
> After in-depth analysis of user behavior data and multi-dimensional competitive market research,
> our team discovered that the core problem lies in the new user onboarding experience not being smooth enough,
> which has led to a first-day retention rate of only 35%, significantly below the industry average of 50%.
> Based on the above analysis, we believe we should start by simplifying the onboarding flow,
> improving user experience through reducing step count and optimizing interaction design... (200 words)

Problem: HWPR is too long; contains AI boilerplate ("after in-depth analysis," "multi-dimensional," "significantly below").

Good — HWPR is concise, focused on judgments

**[HWPR]** Background
> New user first-day retention is 35%. I believe the main cause is onboarding being too complex (5 steps).
> Plan to simplify to 2 steps first, targeting 45% retention.

**[AWOR]** Detailed Analysis
User growth data over the past three quarters: Q1 retention 38%, Q2 35%, Q3 33%, showing a continuous decline.
Competitor comparison: Product A's onboarding has only 2 steps with 52% first-day retention...

---

Exemptions

| Scenario | Condition | |------|------| | Pure record documents | Meeting minutes and other pure records without value judgments — HWPR may be omitted | | Existing mature templates | Weekly reports and other documents with fixed formats — only add HWPR to "judgment/decision" sections |

---

References

• [HWPR/AWOR Document Template](examples/TEMPLATE-HWPR.md)
• Inspiration: Pu Li's HWPR/AWOR documentation methodology

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: addxai
• Source: addxai/enterprise-harness-engineering
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.