| name | human-writing-support |
| description | Support DDx prose work by preserving voice, improving execution-useful clarity, applying deterministic prose findings with judgment, and keeping DDx terminology, headings, tables, paths, commands, and legitimate lists intact. |
Human Writing Support
Trigger: any writing, rewriting, editing, or reviewing of Markdown under
docs/ (specs, ADRs, plans, beads, release notes, website copy).
This is guidance for better human writing, not an AI detector and not a
detector bypass tool. The goal is prose that helps a maintainer or agent
execute, review, or trust a DDx document.
Required Workflow
After any docs edit:
- Preserve the author's intent and DDx terminology.
- Edit the document.
- Run
ddx doc prose --changed.
- Apply high-signal findings.
- Rerun
ddx doc prose --changed.
- Summarize remaining intentional exceptions in the change description.
ddx doc prose is the only public prose checker surface; do not invoke
Vale, Hemingway, or other tools directly. Findings are advisory, not
blocking — apply judgment.
Preservation Rules
Keep these intact unless the task is explicitly about rewriting them:
- Paths, commands, IDs, frontmatter, headings, table structure, API names,
function signatures, and acceptance criteria.
- Quoted source text (do not rewrite quotations).
- Useful technical density — dense can be correct.
- Legitimate technical lists, code blocks, and DDx canonical terms.
Do not "fix" a finding by weakening correct technical prose.
Rewrite Guidance
When applying a finding:
- Replace broad claims with actor / action / artifact / evidence.
- Delete filler transitions when the sentence still reads correctly.
- Prefer shorter wording when it is equally precise.
- Split overstuffed sentences only when doing so improves reviewability.
- Leave a finding unresolved when the flagged text is precise; explain why
in the change description.
Examples
1. Unsupported benefit claim → concrete rewrite
Before:
This change significantly improves the developer experience.
After:
ddx try now writes per-attempt evidence under
.ddx/executions/<run-id>/, so reviewers can inspect prompt, response,
and merge result without rerunning the bead.
2. AI-slop paragraph → shorter actionable sentence
Before:
In today's fast-paced software development landscape, it is critically
important that we leverage best-in-class tooling to ensure our workflows
remain robust, scalable, and future-proof across all stakeholders.
After:
Run ddx doc prose --changed after editing docs so reviewers see the
same findings the agent saw.
3. Token-cost edit → remove filler while preserving meaning
Before (38 words):
It is worth noting that, in order to ensure that the bead is properly
closed out, the agent should make sure to verify that all of the
acceptance criteria have been satisfied before committing the change.
After (15 words):
Verify every acceptance criterion before committing; do not close the
bead with red tests.
4. False positive → leave unchanged
The checker flags "must" in:
AC 6: lefthook run pre-commit must pass.
Leave it. "Must" is the correct contract verb for acceptance criteria.
Record the exception in the change description if ddx doc prose --changed
still surfaces it.
5. Table / path / API sample → do not rewrite
Do not rewrite cells, paths, or API examples even if the checker flags
them. For example, leave this table column intact:
| Command | Purpose |
|---|
ddx bead ready | List beads with all deps satisfied. |
ddx try <id> | Run one bead in an isolated worktree. |
And leave path / API samples such as .ddx/executions/<run-id>/ or
buildAgentRunner(ctx, cfg) unchanged.
Reporting Exceptions
When ddx doc prose --changed still has findings after the second run,
list the intentional exceptions and the rationale (for example: "AC verb
'must' is contract language", "table cells are canonical command names").
Silently ignoring a finding is not acceptable; report it.
