Skip to content
  1. How-to
  2. In real projects
  3. Write READMEs, docs and PR descriptions

Write READMEs, docs and PR descriptions

In one lineHave /pstack:technical-writing sort each section into a doc type first, run every step, then strip the AI tone with /pstack:unslop.

One conversation per READMEFor: You need a README, user docs, or a PR description that doesn't read like AI wrote itFull guide step 5: Design, build, clean up

Copy this first

Write a README
/pstack:technical-writing Write a README for this Node CLI. First tell me which doc type each section should be, and write it once I've confirmed.

AI-written READMEs often have a bit of everything: install steps, philosophy, and an option table, all mixed up. Beginners and people looking up options both have to skip around.

The first rule of /pstack:technical-writing: one doc does one job. It sorts each section into one of four types:

  • Tutorial: follow along once, and see a result at every step.
  • How-to guide: steps to solve one specific problem.
  • Explanation: why it’s designed this way, and the tradeoffs.
  • Reference: options, flags, error codes. Facts only.

If a README needs several types, split it into parts that link to each other.

A Node CLI example

A CLI that batch-exports Markdown notes to HTML needs a README for GitHub:

Node CLI example
/pstack:technical-writing Write a README for this CLI.
Write install and the first export as a tutorial: at each step, tell the reader what output they should see.
Put all options in a separate reference section, built from the real output of --help. Don't make up any options.
When you're done, follow the tutorial from scratch in an empty folder, make sure every command works, and paste the terminal output.
Finally, run /pstack:unslop over it: no em dashes, no "powerful," no "effortless."
  • “Follow the tutorial in an empty folder”: the most useful line. You can argue about style. You can’t argue about whether a command runs.
  • “Built from the real output of –help”: reference docs state facts, and the facts come from the code.
  • “Finally, run /pstack:unslop”: strips the AI tone, plus any words you don’t want.

Where to look after you send it

At the start: how it sorted the types. If philosophy ended up in the getting-started part, correct it right away.

At the end: the terminal output. If a step fails, the tutorial is missing a step.

Strip the AI tone at the end: /pstack:unslop

Copy this
/pstack:unslop the readme changes, no emdashes

Its built-in rules target common AI tone in English: overused em dashes, forced lists of three, empty endings. Add any words you care about to the rules, like “no ‘seamless,’ no ‘empower.’”

Code others will call: write the tutorial first

For a package or API that other code will use, you can write the docs before the code:

Write the tutorial first
/pstack:poteto-mode write a tutorial for how i would use the new config package first. then /pstack:teach me why it beats the current one.

Writing the tutorial first makes it think like the user: what to write first, and what you’ll see. The tutorial also becomes the target to check the code against.

Not sure you asked the right thing: /pstack:sharpen

Copy this
/pstack:sharpen Write onboarding docs for the new billing service.

It doesn’t write the docs. It rewrites your request to be sharper. For example: what an expert would also do, what source material they’d start from, and what could prove the result right. Read the rewrite. If it looks right, send it.

A PR description is a doc too

When it opens a PR, it writes the description with /pstack:technical-writing and runs /pstack:unslop over it. The description is a one-minute brief for reviewers. Empty sections get deleted.

Stuck?

The README still has a bit of everything.

Reply: “Split it the technical-writing way: keep only the tutorial in getting started, move the option table to the reference section, and give the design ideas their own explanation section. Don’t mix them.”

I ran /pstack:unslop, and it still sounds like AI.

List the exact words and phrases that bother you, and add them after the command. For example: “/pstack:unslop this section, no em dashes, no ‘seamless’ or ‘empower,’ sentences under 20 words.” The more specific the rules, the better it does.

/pstack:sharpen didn't write my docs.

It only rewrites the request. Send the rewritten request to /pstack:poteto-mode or /pstack:technical-writing.

The PR description is too long.

Reply: “A PR description is a one-minute brief. One to three sentences per section. Put detailed data in a linked file.”

An unofficial beginner's guide to pstack, not its official docs. pstack is made by poteto; the official repo is the source of truth for commands and behavior. The original guide source is on GitHub.

Hosted by airali. Adapted from Xiaoxiaodong's MIT-licensed guide.