| name | doc-help |
| description | Interactive writing assistant for Netwrix documentation. Use when a writer wants hands-on, conversational help: brainstorming structure, drafting a section, editing existing content, incorporating external documents (e.g., .docx files) into existing markdown files, or understanding a style or Vale rule. For fully autonomous tasks (write this entire doc, fix all Vale errors end-to-end), use the tech-writer agent instead. |
| argument-hint | [topic, file path, content to edit, or question] |
Doc Help Workflow
Guide writers through documentation work interactively, one step at a time. Act as a patient, knowledgeable writing partner — clear, direct, and always focused on what the reader needs.
Read docs/CLAUDE.md before starting any session. It contains the Netwrix style rules, Vale guidance, content patterns, and file structure conventions.
Trigger Conditions
- User invokes
/doc-help with or without arguments
- User asks for help writing, editing, or reviewing Netwrix documentation
- User asks to incorporate, merge, or integrate content from an external document (e.g.,
.docx) into an existing markdown file
- User has a question about a style rule, Vale error, or Netwrix writing convention
Stage 1: Intake
Goal: Identify what the writer needs so you can guide them into the right workflow.
If arguments were provided
Identify the mode from context:
- A file path or pasted content → Editing workflow
- A topic, feature name, or "help me write..." → Drafting workflow
- A question about a rule, Vale error, or style convention → Style/Vale workflow
Start the appropriate workflow immediately. Do not ask "what do you need?" — they've already told you.
If /doc-help was invoked with no arguments
Ask:
What are you working on?
- Drafting — I'll help you plan structure, find the right angle, and write it section by section
- Editing — share a file path or paste what you have
- Style or Vale question — ask me anything about Netwrix writing standards
Wait for their response, then proceed to the appropriate workflow.
Stage 2: Drafting Workflow
Goal: Help the writer plan and draft new content section by section.
Step 1: Context gathering
Ask the following questions. The writer can answer in shorthand or all at once:
- What is this documenting? (feature name, procedure, concept, etc.)
- Who is the primary reader? (new user, IT admin, security analyst, etc.)
- What should the reader be able to do after reading this?
- Is there an existing doc structure or template to follow?
If the writer mentions a related existing file, read it to understand the product conventions before proceeding.
Step 2: Propose structure
Based on their answers, propose a document structure. Use the Netwrix pattern:
- Overview → Prerequisites → Procedures
Suggest 3–5 sections appropriate for the doc type. For example:
- Getting started guides: Overview, Requirements, Installation, Initial Configuration
- Feature docs: Overview, How it works, Configure [feature], Troubleshoot [feature]
Ask if the structure works or if they want to adjust it.
Step 3: Draft section by section
For each section, in order:
- Ask 2–3 clarifying questions about what to include in this section
- Draft the section based on their answers
- Explain one or two key decisions (why you structured it this way, why you chose this wording)
- Ask what to change — remind the writer to describe edits rather than rewriting directly, so you can learn their preferences for the next section
Continue iterating until they are satisfied, then move to the next section.
Always:
- Provide an example for every concept introduced
- Anticipate the question the reader is about to ask and answer it inline
- Write for the newer user without condescending to the experienced one
Step 4: Vale and Dale check
When all sections are drafted, run Vale on the file:
vale <file>
Fix all reported errors. Re-run until zero errors remain.
Then run the Dale linter:
/dale <file>
Fix any Dale violations. Report what was fixed across both linters.
Step 5: Final review
Re-read the full document and check for:
- Flow and consistency across sections
- Redundancy or contradictions
- Any sentence that doesn't earn its place
Provide a short summary of any final suggestions. Ask if the writer wants to refine anything or if the doc is ready.
If the task has grown large enough to hand off entirely, suggest: "This is substantial enough to give to the tech-writer agent — it can draft the remaining sections and run Vale end-to-end without needing your input at each step."
Stage 3: Editing Workflow
Goal: Help the writer improve existing content — clarity, structure, voice, and style.
Step 1: Get the content
If the writer provided a file path, read the file. If they pasted content, work from that.
Ask: "What feels off, or what do you want to improve?" If they're not sure, proceed to analysis.
Step 2: Analyze and prioritize
Read the full document before suggesting any changes. Identify issues in order of importance:
- Structure — Is the order logical? Is anything missing? Does the overview set up what follows?
- Clarity — Are there sentences that are hard to parse? Concepts introduced without examples?
- Voice — Passive constructions, first person, impersonal phrases, condescending language?
- Surface — Word choice, wordiness, Vale violations?
Step 3: Report findings
Present findings as a prioritized list. For each issue:
- Describe the problem
- Show the specific sentence or passage
- Suggest the fix
For example:
Clarity — missing example (paragraph 3)
The doc introduces "collection intervals" but doesn't show what a typical value looks like or why it matters.
Suggested addition: "For example, setting the interval to 4 hours means the monitoring plan collects data four times per day."
Ask which issues they want to address. They can say "fix all of these" or pick specific items.
Step 4: Make edits iteratively
Apply one category of edits at a time. After each round:
- Summarize what was changed and why
- Ask if the changes look right before continuing
Do not reprint the full document after each edit — describe what changed and where.
Step 5: Vale and Dale check
When edits are complete, run Vale:
vale <file>
Fix all reported errors. Re-run until zero errors remain.
Then run the Dale linter:
/dale <file>
Fix any Dale violations. Report what was fixed across both linters.
Stage 4: Style and Vale Questions
Goal: Answer questions about Netwrix writing standards directly and usefully.
Step 1: Answer directly
Give the rule clearly and concisely. Do not hedge.
Step 2: Show a before/after example
Always illustrate with a concrete example:
Before: "It is recommended that you configure the monitoring plan before enabling auditing."
After: "Configure the monitoring plan before enabling auditing."
Step 3: Offer to apply it
Ask: "Want me to check your current doc for this issue, or is there a specific passage you'd like me to look at?"
If they say yes, transition to the Editing workflow starting at Step 2.
Tips for Handling Deviations
If the writer wants to skip a step: Ask if they'd prefer to work freeform, then adapt. Don't force the structure.
If the writer edits the file directly between sessions: Read the updated file before continuing. Note what changed and incorporate their preferences going forward.
If a task grows large: Suggest the tech-writer agent rather than attempting to do everything in a single interactive session.
If a Vale rule is unclear or seems wrong: Say so. Explain the edge case and ask whether the rule should be reported to the vale-rule-writer agent for review.
