{"id":"c459e3a1-2faf-4122-af57-ff7745b0bbd2","shortId":"Ba8yGK","kind":"skill","title":"doc-writing","tagline":"Write documents using the HWPR/AWOR framework -- separating human value judgments from AI-expanded content so critical information is not buried. Triggers when the user requests writing, rewriting, or reviewing document quality.","description":"# Doc Writing (HWPR/AWOR)\n\nIn 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.\n\nFor the detailed template, see [examples/TEMPLATE-HWPR.md](examples/TEMPLATE-HWPR.md).\n\n---\n\n## Core Concepts\n\n- **[HWPR]** (Human Wrote, Please Read): Unknown context + value judgments written by a human. **Must be short** (3-5 sentences).\n- **[AWOR]** (AI Wrote, Optional Read): Detailed content expanded by AI. Can be deleted, modified, or replaced.\n\n---\n\n## Rules\n\n1. **Never modify [HWPR] content** — AI may only read HWPR paragraphs; it must not rewrite, rephrase, merge, or \"polish\" them\n2. **HWPR must be short** — Each HWPR paragraph must not exceed 3-5 sentences; write only: unknown context + value judgments\n3. **Value judgments with humility** — Use phrasing like \"I believe\" / \"current judgment\" / \"possibly\" in HWPR, acknowledging potential error\n4. **[AWOR] can be freely modified** — AI-expanded content may be replaced, deleted, or rewritten at any time\n5. **Consistent marker format** — Use bold markers `**[HWPR]**` and `**[AWOR]**` as headers, followed by paragraph titles\n6. **HWPR uses blockquote** — HWPR body text uses `>` block quotes for visual distinction\n\n---\n\n## Execution Flow\n\n### Mode A: Write a New Document\n\n#### Trigger Conditions\n\nUser requests \"help me write a document,\" \"write a proposal,\" \"draft a PRD,\" etc.\n\n#### Step 1: Guide HWPR Extraction\n\nAsk the user questions to extract core value judgments:\n\n```\nTo write an effective document, I need you to provide the following HWPR content (keep it brief, 1-3 sentences per item):\n\n1. **Background**: Why are we doing this? What is the core problem?\n2. **Judgment**: What do you think we should do? Why this direction?\n3. **Trade-offs**: What was deliberately given up? What are the known risks?\n```\n\n#### Step 2: Confirm HWPR\n\nOrganize the user's answers into HWPR paragraphs and display them for user confirmation. Once confirmed, HWPR is never modified afterwards.\n\n#### Step 3: Generate Complete Document\n\nFollowing the [TEMPLATE-HWPR.md](examples/TEMPLATE-HWPR.md) structure, expand corresponding AWOR paragraphs after each HWPR paragraph.\n\n---\n\n### Mode B: Rewrite an Existing Document\n\n#### Trigger Conditions\n\nUser provides an existing document and requests \"restructure using HWPR/AWOR,\" \"split and label,\" etc.\n\n#### Step 1: Identify Potential HWPR\n\nRead 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.).\n\n#### Step 2: Confirm with User\n\nList the identified results and ask the user to confirm each one:\n\n```\nI identified the following as potentially your value judgments (HWPR) in the document. Please confirm:\n\n1. yes/no \"We chose option B because...\" (paragraph X)\n2. yes/no \"Abandoned real-time push, switched to polling...\" (paragraph Y)\n3. yes/no ...\n```\n\n#### Step 3: Split, Label + Expand\n\nExtract confirmed HWPR into `**[HWPR]**` paragraphs, mark remaining content as `**[AWOR]**`, and expand where necessary.\n\n---\n\n### Mode C: Review a Document\n\n#### Trigger Conditions\n\nUser requests \"review the document,\" \"check HWPR formatting,\" etc.\n\n#### Review Checklist\n\nCheck and report the following issues:\n\n| Check Item | Issue Description |\n|--------|---------|\n| Missing markers | Paragraph has no [HWPR] or [AWOR] marker |\n| HWPR too long | HWPR paragraph exceeds 5 sentences |\n| HWPR contains AI style | HWPR has obvious AI-expansion artifacts (boilerplate, \"in summary,\" etc.) |\n| AWOR contains value judgments | AWOR contains \"we decided\" / \"gave up\" etc. that should be HWPR content |\n| Incorrect marker format | Not using the standard `**[HWPR]**` / `**[AWOR]**` format |\n\nOutput format: List each issue + suggested fix.\n\n---\n\n## Examples\n\n### Bad — HWPR too long, mixed with AI style\n\n```markdown\n**[HWPR]** Background and Judgment\n> After in-depth analysis of user behavior data and multi-dimensional competitive market research,\n> our team discovered that the core problem lies in the new user onboarding experience not being smooth enough,\n> which has led to a first-day retention rate of only 35%, significantly below the industry average of 50%.\n> Based on the above analysis, we believe we should start by simplifying the onboarding flow,\n> improving user experience through reducing step count and optimizing interaction design... (200 words)\n```\n\nProblem: HWPR is too long; contains AI boilerplate (\"after in-depth analysis,\" \"multi-dimensional,\" \"significantly below\").\n\n### Good — HWPR is concise, focused on judgments\n\n```markdown\n**[HWPR]** Background\n> New user first-day retention is 35%. I believe the main cause is onboarding being too complex (5 steps).\n> Plan to simplify to 2 steps first, targeting 45% retention.\n\n**[AWOR]** Detailed Analysis\nUser growth data over the past three quarters: Q1 retention 38%, Q2 35%, Q3 33%, showing a continuous decline.\nCompetitor comparison: Product A's onboarding has only 2 steps with 52% first-day retention...\n```\n\n---\n\n## Exemptions\n\n| Scenario | Condition |\n|------|------|\n| Pure record documents | Meeting minutes and other pure records without value judgments — HWPR may be omitted |\n| Existing mature templates | Weekly reports and other documents with fixed formats — only add HWPR to \"judgment/decision\" sections |\n\n---\n\n## References\n\n- [HWPR/AWOR Document Template](examples/TEMPLATE-HWPR.md)\n- Inspiration: Pu Li's HWPR/AWOR documentation methodology","tags":["doc","writing","enterprise","harness","engineering","addxai","agent-skills","ai-agent","ai-engineering","claude-code","code-review","cursor"],"capabilities":["skill","source-addxai","skill-doc-writing","topic-agent-skills","topic-ai-agent","topic-ai-engineering","topic-claude-code","topic-code-review","topic-cursor","topic-devops","topic-enterprise","topic-sre","topic-windsurf"],"categories":["enterprise-harness-engineering"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/addxai/enterprise-harness-engineering/doc-writing","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add addxai/enterprise-harness-engineering","source_repo":"https://github.com/addxai/enterprise-harness-engineering","install_from":"skills.sh"}},"qualityScore":"0.458","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 16 github stars · SKILL.md body (5,603 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-22T01:02:11.551Z","embedding":null,"createdAt":"2026-04-21T19:04:01.013Z","updatedAt":"2026-04-22T01:02:11.551Z","lastSeenAt":"2026-04-22T01:02:11.551Z","tsv":"'-3':279 '-5':98,149 '1':117,248,278,283,387,451 '2':137,295,322,420,460,735,771 '200':681 '3':97,148,157,307,347,472,475 '33':758 '35':647,718,756 '38':754 '4':175 '45':739 '5':194,537,729 '50':654 '52':774 '6':210 'abandon':462 'acknowledg':172 'actual':70 'add':810 'afterward':345 'ai':16,41,50,63,101,109,122,182,541,547,594,689 'ai-expand':15,49,181 'ai-expans':546 'analysi':605,659,695,743 'answer':329 'appear':399 'artifact':549 'ask':252,429 'averag':652 'awor':100,176,203,358,489,529,554,558,578,741 'b':365,456 'background':284,598,710 'bad':588 'base':655 'behavior':608 'believ':166,661,720 'block':218 'blockquot':213 'bodi':215 'boilerpl':550,690 'bold':199 'brief':277 'buri':24,47 'c':495 'caus':723 'check':506,512,518 'checklist':511 'chose':414,454 'comparison':764 'competit':614 'competitor':763 'complet':349 'complex':728 'concept':80 'concis':704 'condit':232,371,500,781 'confirm':323,338,340,421,433,450,480 'consist':195 'contain':401,407,540,555,559,688 'content':18,106,121,184,274,487,569 'context':87,154 'continu':761 'core':79,258,293,622 'correspond':357 'count':676 'criteria':406 'critic':20 'current':167 'data':609,746 'day':642,715,777 'decid':561 'decis':409 'declin':762 'delet':112,188 'deliber':313 'depth':604,694 'descript':521 'design':680 'detail':74,105,742 'dimension':613,698 'direct':306 'discov':619 'display':334 'distinct':222 'doc':2,36 'doc-writ':1 'document':5,34,53,230,239,265,350,369,376,448,498,505,784,805,817,825 'draft':243 'effect':264 'enough':634 'era':42 'error':174 'etc':246,385,418,509,553,564 'exampl':587 'examples/template-hwpr.md':77,78,354,819 'exceed':147,536 'execut':223 'exempt':779 'exist':368,375,798 'expand':17,51,107,183,356,478,491 'expans':548 'experi':630,672 'extract':251,257,479 'first':641,714,737,776 'first-day':640,713,775 'fix':586,807 'flow':224,669 'focus':705 'follow':206,272,351,439,516 'format':197,508,572,579,581,808 'framework':9 'freeli':179 'full':393 'gave':415,562 'generat':348 'get':46 'given':314 'good':701 'growth':745 'guid':249 'header':205 'help':235 'human':11,43,61,69,82,93,402 'humil':161 'hwpr':81,120,126,138,143,171,201,211,214,250,273,324,331,341,362,390,445,481,483,507,527,531,534,539,543,568,577,589,597,684,702,709,794,811 'hwpr/awor':8,38,57,381,816,824 'identif':405 'identifi':388,426,437 'improv':670 'in-depth':602,692 'incorrect':570 'industri':651 'inform':21 'inspir':820 'interact':679 'issu':517,520,584 'item':282,519 'judgment':13,45,89,156,159,168,260,296,404,444,557,600,707,793 'judgment/decision':813 'keep':275 'known':319 'label':384,477 'languag':417 'led':637 'li':822 'lie':624 'like':164 'list':424,582 'locat':66 'long':52,533,591,687 'main':722 'mark':396,485 'markdown':596,708 'marker':58,196,200,523,530,571 'market':615 'matur':799 'may':123,185,795 'meet':785 'merg':133 'methodolog':826 'minut':786 'miss':522 'mix':592 'mode':225,364,494 'modifi':113,119,180,344 'multi':612,697 'multi-dimension':611,696 'must':94,129,139,145 'necessari':493 'need':267 'never':118,343 'new':229,627,711 'obvious':545 'off':310,412 'omit':797 'onboard':629,668,725,768 'one':435 'optim':678 'option':103,455 'organ':325 'output':580 'paragraph':127,144,208,332,359,363,458,470,484,524,535 'past':749 'per':281 'phrase':163 'plan':731 'pleas':84,449 'polish':135 'poll':469 'possibl':169 'potenti':173,389,441 'prd':245 'problem':294,623,683 'product':765 'propos':242 'provid':270,373 'pu':821 'pure':782,789 'push':466 'q1':752 'q2':755 'q3':757 'qualiti':35 'quarter':751 'question':255 'quick':65 'quot':219 'rate':644 'read':85,104,125,391 'reader':60 'real':464 'real-tim':463 'record':783,790 'reduc':674 'refer':815 'remain':486 'rephras':132 'replac':115,187 'report':514,802 'request':29,234,378,502 'research':616 'restructur':379 'result':427 'retent':643,716,740,753,778 'review':33,496,503,510 'rewrit':31,131,366 'rewritten':190 'risk':320 'rule':116 'scenario':780 'section':814 'see':76 'sentenc':99,150,280,538 'sentences/paragraphs':397 'separ':10 'short':96,141 'show':759 'signific':648,699 'simplifi':666,733 'skill':55 'skill-doc-writing' 'smooth':633 'source-addxai' 'split':382,476 'standard':576 'start':664 'step':247,321,346,386,419,474,675,730,736,772 'structur':355 'style':542,595 'subject':408 'suggest':585 'summari':552 'switch':467 'target':738 'team':618 'templat':75,800,818 'template-hwpr.md':353 'text':216,394 'think':300 'thought':71 'three':750 'time':193,465 'titl':209 'topic-agent-skills' 'topic-ai-agent' 'topic-ai-engineering' 'topic-claude-code' 'topic-code-review' 'topic-cursor' 'topic-devops' 'topic-enterprise' 'topic-sre' 'topic-windsurf' 'trade':309,411 'trade-off':308,410 'trigger':25,231,370,499 'unknown':86,153 'use':6,56,162,198,212,217,380,574 'user':28,233,254,327,337,372,423,431,501,607,628,671,712,744 'valu':12,44,88,155,158,259,403,443,556,792 'visual':221 'week':801 'without':791 'word':682 'write':3,4,30,37,151,227,237,240,262 'written':90 'wrote':83,102 'x':459 'y':471 'yes/no':452,461,473","prices":[{"id":"aafdc836-be7a-4acb-a53e-8ac5ce1486b8","listingId":"c459e3a1-2faf-4122-af57-ff7745b0bbd2","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"addxai","category":"enterprise-harness-engineering","install_from":"skills.sh"},"createdAt":"2026-04-21T19:04:01.013Z"}],"sources":[{"listingId":"c459e3a1-2faf-4122-af57-ff7745b0bbd2","source":"github","sourceId":"addxai/enterprise-harness-engineering/doc-writing","sourceUrl":"https://github.com/addxai/enterprise-harness-engineering/tree/main/skills/doc-writing","isPrimary":false,"firstSeenAt":"2026-04-21T19:04:01.013Z","lastSeenAt":"2026-04-22T01:02:11.551Z"}],"details":{"listingId":"c459e3a1-2faf-4122-af57-ff7745b0bbd2","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"addxai","slug":"doc-writing","github":{"repo":"addxai/enterprise-harness-engineering","stars":16,"topics":["agent-skills","ai-agent","ai-engineering","claude-code","code-review","cursor","devops","enterprise","sre","windsurf"],"license":"apache-2.0","html_url":"https://github.com/addxai/enterprise-harness-engineering","pushed_at":"2026-04-17T08:57:37Z","description":"Enterprise-grade AI Agent Skills for software development, DevOps, SRE, security, and product teams. Compatible with Claude Code, Cursor, Windsurf, Gemini CLI, GitHub Copilot, and 30+ AI coding agents.","skill_md_sha":"2bb35b0ec30f75b2de4b990b4874dfe21666787b","skill_md_path":"skills/doc-writing/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/addxai/enterprise-harness-engineering/tree/main/skills/doc-writing"},"layout":"multi","source":"github","category":"enterprise-harness-engineering","frontmatter":{"name":"doc-writing","description":"Write documents using the HWPR/AWOR framework -- separating human value judgments from AI-expanded content so critical information is not buried. Triggers when the user requests writing, rewriting, or reviewing document quality."},"skills_sh_url":"https://skills.sh/addxai/enterprise-harness-engineering/doc-writing"},"updatedAt":"2026-04-22T01:02:11.551Z"}}