Skip to content

docs: strip internal PR/issue numbers and process tells from blog prose#882

Draft
vivek7405 wants to merge 1 commit into
mainfrom
docs/blog-strip-internal-refs
Draft

docs: strip internal PR/issue numbers and process tells from blog prose#882
vivek7405 wants to merge 1 commit into
mainfrom
docs/blog-strip-internal-refs

Conversation

@vivek7405

Copy link
Copy Markdown
Collaborator

Blog posts carried inline internal tracking references (#605, #646, #489, ...) that read as commit chatter to a reader, plus one process tell ("Verified by dogfooding") that leaks the author's verification workflow into published copy. Neither belongs in a blog.

Closes #881

What changed

What was deliberately kept

  • The author's rhetorical "Let me show you..." / "Let me start with..." openers. These appear in the original pre-existing posts and are the house voice, not a defect.
  • Legitimate #NNN refs elsewhere (agent-docs/, AGENTS.md, docs site) are untouched; only blog/*.md changed.

Verification

  • git grep -nE '#[0-9]{3,4}' -- 'blog/*.md' returns nothing.
  • No "dogfood"/"self-review"/"counterfactual" tell remains in any post.
  • No em-dash or banned pause-punctuation introduced (invariant 11 hook passes).
  • Content-only (no src), so the doc/scaffold/test gates do not apply.

Inline #NNN tracking references read as commit chatter to a blog reader,
who has no context for a PR number, and an author's verification process
("Verified by dogfooding") does not belong in published copy. Remove
every #NNN from blog bodies (rewording each sentence to flow, or dropping
the sentence where the number was its whole point) and the one process
tell, across 16 posts. The established rhetorical voice (the "Let me show
you..." openers from the original posts) is preserved.

Closes #881
@vivek7405 vivek7405 self-assigned this Jul 9, 2026

@vivek7405 vivek7405 left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read every reworded hunk. The prose reads clean, no dangling clauses or orphaned transitions where a trailing sentence was dropped, and every version number, runtime name, and API name survived the number-stripping. The 'Let me show you' voice is intact. Every removal was a tracking pointer or pure history, not a fact a reader needs. Ready to merge.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

1 participant