Anti Slop Document Editing

Anti-slop Document Editing

Choose the document's operating mode before drafting. Do not blend modes by accident.

Core Workflow

1. Identify the reader, their immediate question, their environment, and the consequence of error. Ask only for missing facts that would change the answer.
2. Choose a mode and an output contract: expected reader action or decision, required evidence, source of truth, and owner/date/version where material.
3. Inventory claims. Distinguish facts, assumptions, examples, recommendations, and unresolved items. Do not silently upgrade one into another.
4. Build a structure that lets the reader stop once their question is answered. Make headings describe the answer or task, not the writing process.
5. Draft in concrete language. Give conditions, actions, observable outcomes, and recovery paths where the reader needs them.
6. Apply the selected mode. Use strict rules for safety, procedural, and testable material. Use STE-flavored rules for reader-facing prose that needs clarity without a restricted dictionary.
7. Edit twice: first for reader utility, then for unsupported claims, ambiguity, stale details, and slop patterns.
8. Lint the draft, revise the reported mechanical issues that affect meaning, and lint again. A lower score is a signal, not proof of quality.
9. Verify the output at the appropriate level: run examples; test commands and links; compare requirements against a schema, checklist, or source; have a representative reader perform a task when stakes justify it.

Non-negotiable Editing Rules

• Preserve meaning, scope, constraints, and uncertainty. Improve prose only after establishing what is true.
• Prefer specific nouns and verbs over intensifiers, abstractions, and vague assurances. Name the actor, object, condition, and result.
• Put the answer, action, or decision first. Explain rationale after it when it helps the reader act correctly.
• Remove throat-clearing, self-congratulation, filler transitions, fake quotation marks, and claims of comprehensiveness that the document cannot prove.
• Replace generic examples with executable examples or clearly mark illustrative ones. Include inputs, outputs, prerequisites, and expected result when relevant.
• Do not make text "less AI" by adding forced personality, random variation, or informal filler. Make it more useful instead.
• Keep parallel items genuinely parallel. Split sentences that contain multiple independent obligations, conditions, or outcomes.
• Use normative words deliberately. Define MUST, MUST NOT, SHOULD, and MAY if their distinction matters; otherwise write direct plain English.
• Treat a lint finding as a review prompt. Keep an intentional exception when changing it would make the document less accurate, less usable, or inconsistent with controlled terminology.

Source and Change Discipline

• Cite or link the authoritative source for facts that may be disputed, costly, volatile, or safety-relevant.
• Give version, date, applicability, and configuration boundaries when they affect truth.
• If a fact is unknown, state what is unknown and the next verification action. Never fill the gap with plausible language.
• Maintain one canonical statement for a rule or procedure; reuse or reference it instead of creating near-duplicates.

Final Gate

Before delivery, answer all of these with evidence:

1. Can the intended reader find their task or decision without reading the whole document?
2. Does each material claim have a source, test, clearly bounded assumption, or removal?
3. Can a reader reproduce every promised outcome from the stated prerequisites and steps?
4. Are warnings, failure cases, limits, version constraints, and recovery actions visible where needed?
5. Is every sentence earning its place by changing what the reader understands or does?

Conditional References

• For STE-flavored reader-facing documentation, persona ordering, structures, and examples, read human-friendly.md.
• For strict procedures and independently verifiable technical content, read technical-precision.md.
• To lint Markdown or plain text, run python3 scripts/ste_lint.py --mode flavored draft.md; use --mode strict for procedures. Read linting.md for the checks and limits.
• For the S1000D and ASD-STE100 research basis and compliance limits, read s1000d-research-basis.md. Do not claim S1000D, ASD-STE100, or ATA iSpec 2200 compliance unless the requested standard, issue, project rules, and validation tooling are available.