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

Fields

No fields configured for issues without a type.

Projects

Status
Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions