|
| 1 | +--- |
| 2 | +name: blog-title-review |
| 3 | +description: Review, generate, and choose Ark blog post titles. Use when evaluating title candidates for posts/**/index.mdx and sibling meta.json, when the user is stuck choosing a title, or when a draft needs a click-worthy but accurate title that fits the first three paragraphs. |
| 4 | +--- |
| 5 | + |
| 6 | +# Blog Title Review |
| 7 | + |
| 8 | +## Workflow |
| 9 | + |
| 10 | +1. Read `docs/blog-quality-guide.md`, the target `index.mdx`, and the sibling |
| 11 | + `meta.json` before judging a repository post. If the post is not in the |
| 12 | + workspace, use the text the user provided. |
| 13 | +2. Preserve `category`, `contentType`, `slug`, and publication state unless the |
| 14 | + user explicitly asks for edits. |
| 15 | +3. Extract a title brief before proposing titles: |
| 16 | + - target reader and reading situation |
| 17 | + - the post's concrete object, event, or tension |
| 18 | + - the emotional stake or practical promise |
| 19 | + - the strongest first-three-paragraph hook |
| 20 | + - the current title and why it works or fails |
| 21 | +4. Score existing user candidates first when they exist, then add better |
| 22 | + alternatives only when useful. |
| 23 | +5. Evaluate the title and opening as one unit. If a candidate depends on a hook |
| 24 | + that the first three paragraphs do not pay off, flag the required opening |
| 25 | + change instead of pretending the title is ready. |
| 26 | +6. Do not edit files unless the user explicitly asks for implementation. |
| 27 | + |
| 28 | +## Title Principles |
| 29 | + |
| 30 | +- Prefer a specific unanswered question over a complete summary. |
| 31 | +- Use concrete nouns from the post before abstract virtues. |
| 32 | +- Create tension through contrast, self-recognition, reversal, or specificity. |
| 33 | +- Let the title be click-worthy, but keep the promise payable by the intro. |
| 34 | +- Check word texture. Reject words whose military, corporate, clinical, or |
| 35 | + overly visible metaphorical register clashes with the essay's emotional tone. |
| 36 | +- Avoid titles that sound like generic self-help, corporate slogans, product |
| 37 | + reviews, or manipulative bait. |
| 38 | +- Avoid over-weighting SEO when the post is an essay; the title still needs a |
| 39 | + human reason to click. |
| 40 | + |
| 41 | +## Candidate Patterns |
| 42 | + |
| 43 | +Generate candidates across multiple patterns when the user needs options: |
| 44 | + |
| 45 | +- Collision: combine two unlike elements that the post genuinely connects. |
| 46 | +- Confession: expose the private pressure, mistake, or need behind the post. |
| 47 | +- Reversal: turn an expected belief into the post's real conclusion. |
| 48 | +- Object-led: let a concrete object carry the emotional promise. |
| 49 | +- Direct problem: name the reader's problem in plain language. |
| 50 | +- Quiet essay: use a restrained line when click pressure would cheapen the tone. |
| 51 | + |
| 52 | +## Scorecard |
| 53 | + |
| 54 | +Use 1-5 scores in 0.5 increments. |
| 55 | + |
| 56 | +- `click`: likelihood that the title earns a click from the intended reader. |
| 57 | +- `fit`: accuracy to the full post, not only one vivid sentence. |
| 58 | +- `introFit`: whether the first three paragraphs pay off the title. |
| 59 | +- `specificity`: concrete nouns, situations, or stakes. |
| 60 | +- `emotion`: felt tension without melodrama. |
| 61 | +- `novelty`: freshness compared with generic essay titles. |
| 62 | +- `texture`: whether the key words feel natural in the post's emotional register. |
| 63 | +- `arkTone`: fit with Ark's direct, reflective, engineering-adjacent voice. |
| 64 | +- `baitRisk`: risk of overpromising or misframing the post; lower is better. |
| 65 | + |
| 66 | +When ranking titles, prioritize high `click`, `fit`, and `introFit`, then use |
| 67 | +`baitRisk` as a veto. A high-click title with high bait risk should be marked as |
| 68 | +usable only after an intro rewrite. |
| 69 | + |
| 70 | +## Output Format |
| 71 | + |
| 72 | +Return: |
| 73 | + |
| 74 | +```markdown |
| 75 | +## Title Brief |
| 76 | +- reader: |
| 77 | +- promise: |
| 78 | +- tension: |
| 79 | +- current title: |
| 80 | + |
| 81 | +## Recommendation |
| 82 | +1. `...` - ... |
| 83 | +2. `...` - ... |
| 84 | +3. `...` - ... |
| 85 | + |
| 86 | +## Scorecard |
| 87 | +| Title | Click | Fit | Intro Fit | Specificity | Emotion | Novelty | Texture | Ark Tone | Bait Risk | Note | |
| 88 | +| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | --- | |
| 89 | + |
| 90 | +## Opening Adjustment |
| 91 | +... |
| 92 | +``` |
| 93 | + |
| 94 | +Keep the output shorter when the user asks for a quick choice. Omit |
| 95 | +`Opening Adjustment` when every recommended title already matches the opening. |
0 commit comments