For Cursor

Cursor agent instructions

This file is how Cursor (and any other coding agent) writes or rewrites 8020.in articles.

The public version of the same system is https://8020.in/playbook. When a human pastes that URL into a chat, treat it as this rulebook. When you are already in this repo, read the source files listed below. Do not invent a third house style. If an older checker tool (8020-in-writer) disagrees with these files, these files win; do not draft from it.

1. What you are doing

8020.in is written with AI, openly. Named AI authors on /authors credit the models used, but the useful unit of work is a pass, not a rigid model identity. Any strong model can research, draft, fact-check, rewrite, or review when the person using Cursor asks it to.

Your job is not "write a how-to about the topic." Your job is:

1. Show why the topic is worth seeing through an 80/20 lens.
2. Name where results, pleasure, attention, or failures concentrate.
3. Change what the reader notices, understands, protects, measures, or practices by giving unequal attention on purpose.

If removing the 80/20 lens would leave the same sections in the same order, it fails. The lens must change the editorial selection, not make every sentence depend on brand vocabulary.

The full rules are in writing-system.md. This file tells you which sections to read for which pass, and how to log what you did.

2. Source files (read these)

Do not outline until playbook/briefs/<slug>.md is filled.

3. Workflow (new article or rewrite)

1. Pick the slug and the primary search intent.
2. Pass the concept gate in brief-template.md: the reader's real question, reason to care, positive territory, breadth, exclusions, emotional posture, and memorable takeaway. Do this before collecting studies.
3. Research the concept. List useful field concentration examples, but do not let the easiest statistic choose the thesis and do not force adjacent data into the article.
4. Write the concentration claim in one short sentence. If it becomes a list or sounds grim only because risk data was easy to find, revise the concept.
5. Pick a starting template A-G (writing-system.md §3). Record it in the brief and later in article JSON. Depart from the spine when the audience and concept require it; note why.
6. Outline for continuity and payoff. Every H2 advances the topic-specific thought. Plan one signature insight, not a productized “only-on-8020” block.
7. Draft with a relevant exemplar open for function and feel. Do not copy its sentences or opening rhythm.

For a rewrite, inventory the existing article first: images, sections, sources, links, distinctive examples, and length. Keep a before/after note for every meaningful deletion.

8. Fact-check. Exact percentages need named sources or honest hedges. Label Illustrative: composites. Meet the evidence tier without stacking facts.
9. Cold-reader / voice pass (§8). It may reject the concept or opening, not merely shorten sentences. Break symmetry, match the audience room, compare the first 150 words with the last five related articles, and apply the intro contract rather than a three-paragraph recipe. Delete “not exactly 20%/80%” disclaimers. Keep one plain limit only when a real percentage would be misread, and put it after the opportunity. Rewrite closed or defensive openings into a possibility the reader can use.
10. Second-model pass when possible. Then run the human editorial gate, the rewrite regression gate, and the mechanical publish check (writing-system.md §12) before updating the article including the pass log (§5 below).

4. Short prompt packs

Use the smallest prompt that matches the job. Do not paste the whole playbook unless the task truly needs it. Every pack starts with the same two lines because models are unreliable at naming themselves - the human fills them in.

Improve an existing article

Model for credits: <exact name from playbook/data/authors.json>
Pass: rewrite | fact-check | voice | publish check (pick one)

Read `playbook/docs/cursor-prompts.md`, `playbook/docs/writing-system.md` sections 1, 5, 8, 12, and `storage/app/articles/<slug>.json`.

Improve the article without changing unrelated files.
Keep it clearly 8020.in: make the lens change what the article selects or connects, lead with what is valuable, preserve breadth promised by the query, and give the page a signature insight. Remove generic how-to filler and keep the intro orienting and topic-native.
Before editing, inventory the current article's images, sections, sources, links, distinctive examples, and word count. Preserve them unless the brief explains a deliberate deletion. After editing, compare before and after and run the full creation and rewrite regression gates.

Before editing, confirm which pass you are doing. After editing, append one pass-log entry to `edits` and update `authors`/`models_used` per cursor-prompts.md section 5.

Concept pass (before research)

Model for credits: <exact name from playbook/data/authors.json>
Pass: concept

Read `playbook/docs/writing-system.md` sections 1, 3, 8, and `playbook/docs/brief-template.md`.

Fill only the brief header and Concept gate for `<slug>`.
Start with the Google visitor: what they hoped to understand, why this topic is interesting, what positive or useful territory belongs, what breadth must be acknowledged, and what emotional posture fits.
Do not collect studies yet. Do not choose a thesis because a percentage is easy to find.
Stop if the memorable takeaway is narrow, generic, or only negative.

Write a new article from a brief

Model for credits: <exact name from playbook/data/authors.json>
Pass: draft

Read `playbook/docs/cursor-prompts.md`, `playbook/docs/writing-system.md` sections 1-4, 7-8, 12, and `playbook/briefs/<slug>.md`.

Draft storage/app/articles/<slug>.json from the brief.
Use the selected template as a starting shape, but do not mention template names in reader-facing prose.
The intro must start with prose, orient a Google visitor, make the 80/20 connection clear, promise a useful payoff, and sound like the target audience. Literal 80% and 20% are optional unless the sentence is honest and natural.
Do not invent statistics, studies, scenarios, or sources.
Write the first pass-log entry (pass: draft) and set authors/models_used to the model above only.

Research and fill a brief

Model for credits: <exact name from playbook/data/authors.json>
Pass: research

Create `playbook/briefs/<slug>.md` from `playbook/docs/brief-template.md`.
Preserve the completed concept gate. Find hard anchors, useful field concentration examples, a signature insight, optional lower-value effort, and an evidence tier.
If there is no useful source for a claim, write that plainly. Do not fabricate a clean 80/20 statistic or force adjacent data into the article.
Stop after the brief. Do not draft the article yet.

Fact-check pass

Model for credits: <exact name from playbook/data/authors.json>
Pass: fact-check

Check `storage/app/articles/<slug>.json` against `playbook/docs/writing-system.md` sections 1, 2, 7, and 12.
Flag exact percentages without sources, unlabeled illustrative examples, weak hedges, broken links, and claims that sound more certain than the evidence.
Make minimal edits only where the fix is clear. Append a pass-log entry listing what you changed and what you flagged but left.

Voice pass

Model for credits: <exact name from playbook/data/authors.json>
Pass: voice

Check `storage/app/articles/<slug>.json` against `playbook/docs/writing-system.md` section 8.
Read it cold as a visitor from Google. If the concept is too narrow, too negative, or does not cover the territory promised by the query, stop and flag a concept rewrite instead of polishing it.
Otherwise make the article sound like the target reader's world, not like a template.
Break repeated section shapes, shorten dense sentences, remove AI sludge, and keep the 80/20 framing concrete without forcing literal proportions. Compare the first 150 words with the last five related articles; vary paragraph count, entry point, and rhythm. Delete defensive ratio paragraphs. The opening should make the reader want to look again.
Do not add new claims unless needed for clarity. Append a pass-log entry.

Publish check

Model for credits: <exact name from playbook/data/authors.json>
Pass: publish check

Run `playbook/docs/writing-system.md` section 12 on `storage/app/articles/<slug>.json`.
Also open /playbook/made/<slug> (or run pb_article_checks from playbook/lib/article.php) and report the mechanical checks.
Return a short pass/fail list and fix only obvious mechanical misses. Append a pass-log entry.

5. Credits and the pass log (mandatory on every pass)

Every pass that touches an article file appends one entry to edits:

{
  "date": "YYYY-MM-DD",
  "pass": "research | draft | fact-check | voice | rewrite | review | publish check",
  "model": "<exact public name from authors.json>",
  "note": "One line: what changed, what was flagged and left."
}

Rules:

• model is the name the human gave you in Model for credits. If they did not give one, ask before writing the entry. Never write Cursor Agent, 8020.in Editorial, Writer tool, or your own guess at your model name.
• Add the same name to authors and models_used if it is not already there. Keep the two arrays identical.
• Never leave model blank, and never invent a name that is not in authors.json.
• Older entries use {author, at, message} or {date, note}. Leave them; playbook/lib/article.php normalises them for display. Do not rewrite history.
• The pass log is public at /playbook/made/<slug> and summarised under every article. Write the note for a reader, not for yourself.

6. Article JSON

{
  "title": "Topic Name",
  "slug": "topic-name",
  "seo_intent": "Primary query or outcome promise",
  "template": "A",
  "viz": false,
  "content": "<p>Intro starts here.</p>",
  "modified": "YYYY-MM-DD HH:MM:SS",
  "date": "YYYY-MM-DD HH:MM:SS",
  "attachment_url": "/img/articles/...",
  "authors": ["ChatGPT-5.1", "Gemini 3.1 Pro"],
  "models_used": ["ChatGPT-5.1", "Gemini 3.1 Pro"],
  "edits": [
    {"date": "2026-09-01", "pass": "draft", "model": "ChatGPT-5.1", "note": "First draft from brief."},
    {"date": "2026-09-02", "pass": "fact-check", "model": "Gemini 3.1 Pro", "note": "Sourced two percentages; hedged one; removed an unsourced study."}
  ]
}

Field rules (full detail in writing-system.md §8 and §11):

• title is the slug display name only (Relaxation). The page already prints "80/20 Rule in".
• seo_intent is metadata only. Never an H2.
• content is HTML. Headings that should use the article heading size take class="heading". A table sits in <figure class="table-block">. Every <a href> has target="_blank" and rel="noopener noreferrer". Clause breaks use - , no em dashes. Bold only as a lead-in.
• "viz": true only for a full pack of ~4-5 charts. Default false.

7. Voice and evidence, in one breath

The full tables are writing-system.md §7 (evidence tiers, claim-level bar) and §8 (audience fit, intro rules, typography). Do not re-learn them from here. The three things agents most often miss:

• Audience first. Labubu is not aerospace is not Bible study. Swap the topic noun; if the voice still fits, rewrite.
• Exact % needs a named source or an honest hedge. An honest 4%/96% beats a fake 80/20. Prefix invented scenarios with Illustrative:.
• No template or pipeline words in the article. No "Tier-1", no "Concentration Finder", no "the point of this article".

8. Multi-model handoff

Prefer a different pass in a follow-up chat, on a different model over one giant dump. The state that carries between passes is:

1. playbook/briefs/<slug>.md - the research and the claim.
2. The article JSON - the current text.
3. The pass log in edits - what was already done and what was flagged.

Typical handoff: research + brief (model A) -> draft (model A or B) -> fact-check + voice (model B) -> publish check (model C or the human). Read the pass log before you start so you do not redo a finished pass.

If you only get one pass, still run the §12 checklist on yourself before editing JSON, and log it.

9. Quotes

Quotes on /quotes are honestly invented AI-author quotes. They are not historical attributions and are not article passes.

• Keep submissions in playbook/quotes/submissions/*.json.
• A later editor assembles config/quotes.php from those submissions.
• Never assign a quote to a different model than the submission. Do not rewrite another model's quote to "improve" it.

10. What not to touch

• Do not put playbook jargon in the reader-facing article.
• Do not add a generic FAQ.
• Do not add a single decorative Pareto chart.
• Do not edit edits entries you did not write.
• Do not add a new public author name without adding it to playbook/data/authors.json first.

11. Improving this playbook

The playbook is meant to get better in public.

• Rules live in playbook/docs/. /playbook renders those files directly.
• writing-system.md owns the rules and the only publish checklist. style-guide.md owns SEO, length, and label conventions. engine.md owns the brand-neutral method. Do not duplicate a rule across files; link to it.
• Site-specific paths and names live in playbook/config.php, not in the docs.
• If a rule is hard to follow in Cursor, tighten the section in writing-system.md and, if it affects the prompt packs, this file.