Skip to content

Strip internal PR/issue numbers and process tells from blog prose #881

Description

@vivek7405

Problem

Several published blog posts carry inline internal tracking references (#605, #646, #489, ...) and a process/reasoning tell ("Verified by dogfooding") that read as commit chatter, not reader-facing prose. A blog reader has no context for a PR number, and an author's internal verification process should never surface in published copy. Example the user flagged, from blog/import-only-pages-zero-js.md:

...the boot ships just the interactive component leaves it imported (#605, #609). A page ships whole only when it does client work of its own, and webjs doctor names the reason when it happens (#646, #666).

Design / approach

Remove every inline #NNN reference from blog PROSE, rewording the sentence so it flows naturally (the feature/behaviour is what matters, not the tracking number). Remove process/reasoning artifacts like "Verified by dogfooding". Keep the author's established rhetorical voice (the "Let me show you..." openers appear in the original pre-existing posts and are NOT a defect; do not strip those). Rewrite the specific import-only-pages-zero-js.md paragraph above so it reads as clean blog prose.

Scope (15 blog files carry #NNN, found via git grep -nE '#[0-9]{3,4}' -- 'blog/*.md'):

  • import-only-pages-zero-js (8), native-sqlite-node-and-bun (6), ssr-action-seeding-no-refetch (4), nextjs-16-file-routing-parity (3), async-render-in-web-components (3), streaming-server-actions-llm (2), ship-zero-javascript-display-only-components (2), server-actions-without-react-server-components (2), node-and-bun-no-build (2), no-build-frontend-performance (2), component-suspense-streaming (2), bun-serve-vs-node-http (2), prisma-vs-drizzle-default-orm (1), optimistic-ui-without-boilerplate (1), full-stack-type-safety-no-build (1).
  • Process tell: blog/per-action-middleware.md:88 "Verified by dogfooding: ...".

Implementation notes (for the implementing agent)

  • Where to edit: blog/*.md at the repo root only (the marketing site reads these directly via website/modules/blog/queries/list-posts.server.ts, BLOG_DIR = <repo>/blog). Do NOT touch agent-docs/, AGENTS.md, or the docs site, where #NNN refs are legitimate.
  • Find every occurrence: git grep -nE '\(#[0-9]{3,4}\)|#[0-9]{3,4}' -- 'blog/*.md'. Also scan for process tells: git grep -niE 'verified by dogfooding|self-review|counterfactual|dogfood' -- 'blog/*.md'.
  • Reword, do not just delete the parenthetical and leave a dangling clause. Read each sentence and make it flow.
  • Landmine: AGENTS.md invariant 11 bans em-dashes and space-hyphen-space / space-semicolon-space pause punctuation; the .claude/hooks/block-prose-punctuation.sh hook scans NEW content and blocks a violating commit. Keep prose clean.
  • Do NOT strip the author's "Let me..." rhetorical openers (they are in the original 29 posts; they are the house voice, not a defect).
  • Content-only (no src), so the doc/scaffold/test commit gates do not apply.

Acceptance criteria

  • git grep -nE '#[0-9]{3,4}' -- 'blog/*.md' returns nothing
  • No "Verified by dogfooding" or similar process/reasoning tell remains in any blog post
  • The flagged import-only-pages paragraph reads as clean blog prose
  • Author voice (the "Let me..." openers) preserved; sentences still read naturally after the numbers are removed
  • No em-dash / banned pause-punctuation introduced (hook passes)
  • All changes in a single PR

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

Status
Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions