---
description: Use when reviewing or editing raw LLM-generated notes, plans, reviews, or research artifacts into concise human-oriented durable documents while preserving traceability.
polytoken:
  tags: [documentation]
---
# Refining Human Documents

Use this skill when an artifact is useful but still sounds like an LLM transcript, scratchpad, process log, or AI-generated commentary. The goal is not to erase provenance; it is to make durable text clear, concise, purposeful, and useful to future humans. Agents often miss their own LLM-speak in the moment, so this pass is especially valuable as a later review by a different agent or model family.

Announce: "using the refining-human-documents skill to turn this into a durable human-oriented document"

## When to use

Use for:

- initiative summaries;
- design dossiers;
- decision records;
- research syntheses;
- review/adjudication reports;
- implementation handoff notes intended to survive beyond the current session.

Do not use for:

- raw evidence that must remain verbatim;
- logs, transcripts, or reviewer reports where exact wording matters;
- public docs that need focused technical review beyond document prose cleanup.

## Editing goals

Use this rubric as a guide:

1. **Does it stay true?** Keep the decisions, evidence, links, constraints, and uncertainty intact.
2. **Can a future maintainer read it quickly?** Put the point where they will find it.
3. **Is every sentence earning its keep?** Cut process narration, repeated caveats, and meta-commentary.
4. **Does it sound like a person taking responsibility?** Prefer plain, direct language over hype, apology, or model voice.
5. **Can someone act on it?** Make open questions, risks, follow-ups, and next steps explicit.

## Remove or rewrite LLM-speak

Remove or rewrite patterns like:

- "I investigated..."
- "The user asked..."
- "It seems like..." when evidence is available;
- "This is a comprehensive..."
- "In summary" when the section is already a summary;
- repeated caveats, formulaic contrasts, self-posed rhetorical questions, dramatic fragments, and vague stakes language;
- tool/process narration unless it is evidence.

Rewrite into durable prose:

- Bad: "Here’s the thing: this plan isn’t just about adding a facet. It’s about creating a more nuanced workflow landscape that can evolve over time."
- Good: "The plan facet override keeps Polytoken’s default handoff behavior and adds guidance for iterative planning, decision records, and executable-slice readiness."

- Bad: "The goal tree serves as a powerful foundation for navigating complexity, enabling agents to seamlessly drill down from big-picture goals to actionable next steps."
- Good: "Use the goal tree to track goals, research questions, decisions, pivots, and executable slices with stable Markdown links."

## Preserve evidence

Do not collapse evidence into vague claims. Keep links and references close to the claims they support.

Prefer:

```md
Decision: Override the project `plan` facet compatibly.

Evidence:
- Polytoken facets can transclude shipped prompt chunks.
- The override uses a `transclude("polytoken://system_prompts/plan.md")` directive (wrapped in double curly braces).
```

Avoid:

```md
Decision: We learned some things and made a plan override.
```

## Separate current state from history

A durable document should present the current state. Preserve history by linking to decision records, prior documents, or version-control history rather than carrying stale content inline.

Use sections such as:

- Current decision
- Rationale
- Evidence
- Alternatives considered
- Consequences
- History references, when needed

Do not leave obsolete alternatives interleaved with the current recommendation. If history matters, link to the decision ledger, prior document, ticket, or commit that preserves it.

## Editing process

1. Identify the document's audience and purpose.
2. Identify which content is durable: decisions, evidence, constraints, risks, open questions, next steps.
3. Identify which content is process residue or LLM-speak: narration, apologies, repeated uncertainty, tool chatter, false starts, formulaic reversals, filler phrases, and vague declaratives.
4. Rewrite for structure and tone.
5. Verify that every important decision still has evidence or rationale.
6. Verify that open questions and risks remain visible.
7. If the rewrite changes meaning, stop and surface the discrepancy instead of silently editing it away.

## Output expectations

When editing a file, report:

- what audience/purpose you optimized for;
- major structure changes;
- any meaning-preserving compression;
- any claims you could not verify;
- any follow-up edits that would require domain input.

## Checklist

Before finishing, confirm:

- [ ] Removed model/process-centric narration and formulaic AI prose unless needed as evidence.
- [ ] Preserved decisions, evidence, links, constraints, and uncertainty.
- [ ] Made current decisions easier to find than historical exploration.
- [ ] Made open questions and follow-ups explicit.
- [ ] Improved concision without deleting important rationale.
- [ ] Avoided inventing facts or strengthening claims beyond the evidence.
