prose-editing

Files (7)

• SKILL.md
• openai.yaml · agents/
• compression.md · references/
• mechanical.md · references/
• voice.md · references/
• NOTICE · scripts/
• lint.py · scripts/

SKILL.md (first lines)

# Prose editing

Edit an existing draft without changing what it claims. The caller supplies
the prose and, when it knows, the register. Return only the prose when another
skill invokes this one.

## Choose the operation

Explicit edit intent wins. A request to rewrite, tighten, or humanize remains
an edit even when it also asks for findings or a score.

Use `audit` only when the caller explicitly asks for no changes, an audit, or
findings without a rewrite. Text written by somebody else is not automatically
read-only. Protect quoted third-party passages, but offer or make a requested
rewrite of the surrounding draft.

## Choose the primary register

A caller-provided register wins. Otherwise, use the document's primary purpose:

| Register | Primary purpose | Loaded references |
|---|---|---|
| `strict` | procedure, runbook, safety text, operator-facing error | [mechanical](references/mechanical.md) and all of [compression](references/compression.md) |
| `flavored` | README, technical docs, PR or MR body, Jira prose, code comment | [mechanical](references/mechanical.md) and the shared part of [compression](references/compression.md) |
| `voiced` | announcement, community message, blog post, personal prose | [mechanical](references/mechanical.md) and [voice](references/voice.md) |
| `audit` | explicit no-change inspection | all three references; recommendations follow the document's primary purpose |

Purpose outranks a byline. A technical README with an author's name remains
`flavored`. When the purpose is genuinely ambiguous and choosing wrong would
materially change the rewrite, ask one focused question. Otherwise use
`voiced`, which makes the least structural change.

Use one numeric primary score. Do not invent a register map. In a mixed
document, keep its primary register and manually apply `strict` rules to
procedural and safety sections. This local override does not produce a second
score.

If the user supplies a sample of their own writing, read it before the draft.
Its stable sentence rhythm, vocabulary, punctuation, transitions, and quirks
govern `voiced` edits. A sample can justify em dashes, curly quotes, repeated
openings, or other deliberate habits that are weak evidence by themselves.

## Prepare a safe working copy

Never write beside this installed skill. Create a unique directory with the
system temporary-directory API. Keep these paths inside it:

- `source.md`: an unchanged snapshot used for the meaning check.
- `rewrite.md`: the only bytes scored before and after; edit this file.
- `before.json`: the baseline report for that exact normalized `rewrite.md`
  path.
- `voice.md`: an unchanged snapshot of a supplied writing sample, when present.

For pasted text, write the supplied bytes to `source.md`, then copy it to
`rewrite.md`. For a user file, copy the file to both paths and do not touch the
original until the rewrite passes every guard. Use process argument arrays
where the host supports them. If a shell is unavoidable, quote every path,
including the trusted skill directory and all temporary paths. Never paste a
user-controlled path into an unquoted command.

When the user supplies a writing sample, copy its exact bytes to `voice.md` and
pass `--voice-sample "<unique-temp-dir>/voice.md"` on both linter runs. Omit the
option on both runs when there is no sample. A different or changed sample makes
the baseline incompatible.

Resolve `scripts/lint.py` relative to this `SKILL.md`. The equivalent shell
shape without a writing sample is:

```bash
python "<skill-dir>/scripts/lint.py" --json --register <register> \
  "<unique-temp-dir>/rewrite.md" > "<unique-temp-dir>/before.json"
```

When a sample exists, insert
`--voice-sample "<unique-temp-dir>/voice.md"` after the register argument.

Use the host's UTF-8 file APIs or redirection in the temporary directory. Do
not use a fixed `before.json`. Delete the unique directory after delivery.

## Edit loop

Skip to [Audit](#audit) for `audit`. For an edit:

1. Load the references named by the register. Read every rule that applies.
2. Score `rewrite.md` and save the complete JSON as `before.json`.
3. Read all `violations`, `samples`, `markers`, and manual checks. A zero score
   does not clear a marker or a rule that needs judgment.
4. Build a private source inventory. Record every proposition, condition,
   exception, scope qualifier, modal force, name, number, version, date, quote,
   citation, identifier, and safety consequence.
5. Rewrite `rewrite.md`. Change the smallest useful span, except when several
   patterns cluster in one paragraph; then rewrite that paragraph around its
   concrete point.
6. Score the same normalized `rewrite.md` path against `before.json`:

   ```bash
   python "<skill-dir>/scripts/lint.py" --json --register <register> \
     --baseline "<unique-temp-dir>/before.json" \
     "<unique-temp-dir>/rewrite.md"
   ```

   When the baseline used a writing sample, insert the same
   `--voice-sample "<unique-temp-dir>/voice.md"` argument after the register.

   A baseline metadata or path mismatch is a failed verification, not a score.
   Correct the invocation and rerun it. Never reuse a report from another
   register, quote policy, file, or linter score version.
7. Make at most one more rewrite-and-score pass.
8. Compare `source.md` with `rewrite.md` in both directions. Every source
   proposition and qualifier must survive, and every output proposition must
   come from the source or an explicit user instruction. Preserve `must`,
   `should`, `may`, `can`, uncertainty, negation, and exceptions unless the
   source itself licenses the change.
9. Run the manual checklist and an adversarial final read. Ask: "What still
   sounds generated?", "What fact or limit disappeared?", and "What did this
   rewrite add?" Repair any defect those questions expose.
10. Only now copy the final prose to the requested destination. For a user
    file, replace its prose while preserving protected spans. For pasted text,
    return the rewrite.

From redhat-developer/rhdh-skills, Apache-2.0.

More from redhat-developer/rhdh-skills