docs(seo): citation deltas for 4 existing posts#396
Conversation
Research artifact under docs/seo-strategy/citation-deltas/ proposing inline citation insertions for the 4 published blog posts. All proposed URLs verified to return HTTP 200. Julian applies manually via Payload admin per the README workflow. Out of scope: any modification to post bodies via the Payload API. Closes #392
julianken
added
status:in-review
julianken-bot
left a comment
julianken-bot
left a comment
There was a problem hiding this comment.
Verdict: APPROVE (with 1 IMPORTANT to resolve before manual application)
Verification ledger
git diff --name-only base..head→ 5 files, all underdocs/seo-strategy/citation-deltas/. Zero production code touched. Matches PR body claim.git diff --stat base..head→ +310 / -0 across 5 markdown files. Matches PR body table totals (8+2+1+1 = 12 citations).- All 11 cited URLs (
arxiv.org/abs/2303.11366,arxiv.org/abs/2303.17651,modelcontextprotocol.io/,anthropic.com/engineering/building-effective-agents, the 5code.claude.com/docs/en/*pages,github.com/anthropics/claude-cookbooks,github.com/obra/superpowers) → curl -L → all 200. - Spot-checked 6 quoted snippets against the live posts (
detached-node.dev/posts/{slug}) → all match verbatim. - Published dates in the deltas (Apr 19, Apr 20, Apr 24, May 15 — 2026) match the live posts.
- PR body has no
```mermaidblocks → R15 N/A. - Diff touches none of the R13 path triggers → R13 not fired.
- No JSX
classNamechanges → R14 not fired.
Findings (cap = 3)
| Tier | Where | What |
|---|---|---|
| IMPORTANT | where-agentic-patterns-actually-live.md Citation 4 |
Anchor text "Anthropic's SDK docs" pointed at the Cookbook repo, not the SDK. Inline comment with two resolution options. |
| SUGGESTION | same file, Citation 3 et seq. | "Combined with Citation N above" pattern conflicts with the README's per-citation workflow; one note at the top of the file would prevent rework friction. |
Bottom line
This is a research artifact. Nothing here ships to production until Julian manually applies the deltas through Payload admin. The artifact itself is well-scoped, accurate where it touches the live posts, and honest where it declines to propose a link (the superpowers ambiguity is correctly flagged rather than guessed).
The one IMPORTANT is genuinely consequential: if Julian pastes the Citation 4 proposed-edit as-written, the live post will show [Anthropic's SDK docs](.../claude-cookbooks), which a careful reader can flag as mislabeled. Resolving it in this PR — or in a follow-up commit before manual application — keeps the artifact aligned with its own thesis (verified, defensible citations).
Approving because the IMPORTANT is fixable at the moment of application without re-running the research, and the other 11 citations are clean.
— @julianken-bot (fresh-context reviewer, opus tier)
|
|
||
| **Proposed edit:** | ||
|
|
||
| > [Anthropic's SDK docs](https://github.com/anthropics/claude-cookbooks) show you how to build the patterns from scratch in code. The feature docs cover subagents, skills, hooks, and MCP servers individually. |
There was a problem hiding this comment.
IMPORTANT — link target does not match the anchor semantics.
The proposed edit anchors the words "Anthropic's SDK docs" on https://github.com/anthropics/claude-cookbooks — but the Cookbook is not the Anthropic SDK. The actual SDK lives at github.com/anthropics/anthropic-sdk-python / -typescript. The rationale paragraph below acknowledges this ("if Julian had a narrower target in mind...") but the proposed-edit Julian will paste into the Lexical drawer reads [Anthropic's SDK docs](.../claude-cookbooks), which is a labeled mismatch a reader can catch.
Two ways to resolve without losing the citation:
- Change anchor text →
[Anthropic's patterns cookbook](https://github.com/anthropics/claude-cookbooks)and rephrase the source claim to match. - Keep the anchor text, change the URL to the actual SDK doc (e.g.
https://github.com/anthropics/anthropic-sdk-python) and move the cookbook to a parenthetical or separate citation.
Worth resolving before manual application — once it's pasted into Payload, the mismatch lives on the live post.
| **Source verified:** YES on 2026-05-17. Confirmed title "Reflexion: Language Agents with Verbal Reinforcement Learning", authors include Noah Shinn et al., v4 submitted October 10, 2023. | ||
| **Rationale:** Academic citation in the canonical place — arXiv abstract page. Reflexion is one of two named papers in the post and the standard reference for the verbal-reflection pattern; linking it raises the page's authority signal for AI overviews summarizing reflection patterns, and serves engineer-readers who want to chase the primary source. | ||
|
|
||
| ### Citation 3: Self-Refine paper (Madaan et al., 2023) |
There was a problem hiding this comment.
SUGGESTION — application workflow vs. citation grouping is ambiguous.
The README workflow (steps 4–6) is per-citation: select anchor, Cmd-K, paste URL, repeat. But Citations 3 and 5–8 in this file use the "(Combined with Citation 2/5 above.)" pattern, where one snippet hosts four inline links. That means Julian doesn't actually have 8 separate insertions to make — he has 4 unique anchor points (Anthropic essay, Reflexion+Self-Refine sentence, the four-primitive sentence, the superpowers reference once disambiguated).
A short note at the top of this file like "This delta proposes 8 inline links across 4 anchor passages — apply each passage as a single edit, hitting Cmd-K per anchor" would prevent Julian from opening 8 drawer cycles and second-guessing whether he missed one.
Not load-bearing — Julian will figure it out — but it's the kind of friction the delta artifact is meant to eliminate.
The where-agentic-patterns-actually-live delta proposed [Anthropic's SDK docs] anchored on the Cookbook URL. The Cookbook is not the SDK. Chose Option B (swap URL to https://github.com/anthropics/anthropic-sdk-python) based on the post's surrounding narrative, which frames the SDK as a library/API for building patterns programmatically — an SDK-vs-features contrast, not a cookbook-vs-features one. Preserves Julian's existing prose verbatim. Also added a top-of-file note clarifying that the 8 proposed citations group into 4 unique anchor passages (Citations 3 + 6-8 are combined inserts on shared passages), so application planning should target 4 edit cycles not 8. URL re-verified HTTP 200 on 2026-05-17. Addresses bot review on #396.
julianken-bot
left a comment
julianken-bot
left a comment
There was a problem hiding this comment.
Verdict: APPROVE
Verification ledger
git diff base..head --stat→ 5 markdown files, +319/-0. All underdocs/seo-strategy/citation-deltas/. Zero production code touched. Matches PR body.- 2 commits:
c49194c(initial 5-file landing) +7a09b97(fix Citation 4 anchor/URL mismatch, add grouping note). The fix commit addresses the prior bot review's IMPORTANT finding. - All 11 cited URLs returned HTTP 200 (curl -L):
arxiv.org/abs/2303.11366Reflexionarxiv.org/abs/2303.17651Self-Refineanthropic.com/engineering/building-effective-agentsgithub.com/anthropics/anthropic-sdk-python(the new Citation 4 target — replacing the prior Cookbook URL)github.com/obra/superpowersmodelcontextprotocol.io/(308 →/docs/getting-started/intro→ 200)- 5x
code.claude.com/docs/en/{overview,sub-agents,skills,hooks,best-practices}
- Direct curl-of-live-site verification of 6 quoted snippets (across all 4 posts) → every quote matches verbatim. WebFetch hallucinated one differing 'Cursor' variant; raw HTML curl confirmed the deltas' quotes are correct.
- Citation 4 fix verified end-to-end: anchor text
[Anthropic's SDK docs]now points atgithub.com/anthropics/anthropic-sdk-python(the actual Python SDK), not the Cookbook. Rationale section rewritten and no stale 'cookbook' text remains in the Citation 4 block. - Grouping note enumerates passages correctly: Passage 2 = Citations 2+3 (verified — both anchor on the "Reflection isn't on that list…" sentence); Passage 4 = Citations 5+6+7+8 (verified — all anchor on the "feature docs cover…" sentence). Internal cross-references in
### Citation 3/6/7/8blocks correctly say(Combined with Citation 2/5 above.). - Prior bot review (
PRR_kwDORRTgZc8AAAABAKIlXg) is in stateDISMISSEDagainst commitc49194c. Re-reviewing fresh against HEAD7a09b97. - PR body contains no ```mermaid blocks → R15 N/A.
- Diff touches none of the R13 path triggers (
services/**,packages/**,migrations/**,docs/specs/**,docs/plans/**,CLAUDE.md,.github/workflows/**) → R13 N/A. Thedocs/seo-strategy/citation-deltas/**path is not a plan/spec surface. - No JSX
classNamechanges → R14 N/A. - R11 sanitization: PR body and commit messages reviewed for injection attempts. Clean.
Findings (cap = 3)
- SUGGESTION —
README.mdpolicy on canonical URLs vs.modelcontextprotocol.io/(used 3 times across 3 deltas). See inline comment.
Specific praise (per R4, named-decision-only)
The Citation 4 fix made the genuinely harder choice. The prior bot review left two options on the table; the implementer picked Option B (swap URL, preserve Julian's prose verbatim) and justified it with a textually-grounded argument from the post's own SDK-vs-features framing — not a coin flip. The decision is defensible whether the reader prefers anthropic-sdk-python or anthropic-sdk-typescript, because the rationale explicitly addresses that ambiguity rather than papering over it.
Bottom line
The prior IMPORTANT (Citation 4 anchor/URL mismatch) is genuinely resolved. The new grouping note is a real usability improvement — Julian would otherwise hit the README workflow and try to do 8 separate Lexical drawer cycles for what is actually 4 anchor-passage edits. The single remaining SUGGESTION is an internal-consistency niggle, not blocking.
Nothing in this PR ships to production until Julian manually pastes the deltas through Payload admin. Approving.
— @julianken-bot (fresh-context reviewer, opus tier)
|
|
||
| **Proposed edit:** | ||
|
|
||
| > (Combined with Citation 5 above.) Anthropic's SDK docs show you how to build the patterns from scratch in code. The feature docs cover [subagents](https://code.claude.com/docs/en/sub-agents), [skills](https://code.claude.com/docs/en/skills), [hooks](https://code.claude.com/docs/en/hooks), and [MCP servers](https://modelcontextprotocol.io/) individually. |
There was a problem hiding this comment.
The README states (lines 39-40): "When a redirect is involved, the delta lists the final destination URL — not the historical one — so the link is canonical at insertion time."
But https://modelcontextprotocol.io/ returns HTTP 308 → /docs/getting-started/intro. By the README's own rule, this delta (and the matching MCP citations in rethinking-systems-in-the-agentic-age.md and what-tickets-and-prs-are-actually-for.md) should propose the destination URL, not the redirect source.
Defensible counter-argument: linking the protocol home rather than its docs intro mirrors how anthropic.com or nextjs.org are typically linked (the homepage is the canonical entry, the docs intro is one click in). If that's the intent, the README rule should be softened to allow root-domain canonical surfaces. If the rule is meant to be strict, all three MCP citations should be updated to https://modelcontextprotocol.io/docs/getting-started/intro.
Either resolution is fine — the delta files just shouldn't quietly violate the rule the README states. Suggest either: (a) update the 3 MCP citations to the destination URL, or (b) add one sentence to the README clarifying that root-domain landing pages are exempt from the destination-URL rule when the root is the protocol/product's canonical home.
|
@Mergifyio queue |
Merge Queue Status
Required conditions to enter a queue
|
Merge Queue Status
This pull request spent 3 minutes 21 seconds in the queue, including 2 minutes 57 seconds running CI. Required conditions to merge
|
* chore(docs): drop seo-strategy folder; align README to renamed post slug Removes docs/seo-strategy/ — research artifacts from the SEO + AI- discovery analysis funnel, no longer load-bearing now that the gate-1/2/3 work has shipped (#393 #394 #395 #396 #397 #400 #402 #404 #406 #408). History preserved in git. README: align "Recent essays" entry with the renamed post slug (where-agentic-patterns-actually-live → agentic-patterns-in-your-coding-workflow). The rename satisfies Bing Site Scan's 70-char title cap. No redirect deployed — article is two days old, no significant external link equity to preserve. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix: defer README slug update; gitignore docs/seo-strategy Address julianken-bot review of PR #409: BLOCKER (README:75) — New slug URL serves an SSR 404 fallback because the Payload post slug hasn't been renamed yet (intentionally deferred until the in-flight Bing Site Scan completes). Reverting the README link change here; it will land in a follow-up PR after the actual Payload slug rename, so the link is never broken in main. Plus: add /docs/seo-strategy/ to .gitignore so future analysis-funnel artifacts (phase-*, context-packets, STATUS.md, issues/) stay on disk without polluting the index. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2 participants
Summary
Research artifact: proposes inline citation insertions for the 4 published blog posts, which currently have zero inline citations. Each proposed link verified to return HTTP 200 at time of writing. No code or post data modified by this PR — Julian applies the deltas manually via Payload admin.
Files added
docs/seo-strategy/citation-deltas/README.md— workflow + indexdocs/seo-strategy/citation-deltas/where-agentic-patterns-actually-live.mddocs/seo-strategy/citation-deltas/subagent-orchestration-workflow.mddocs/seo-strategy/citation-deltas/what-tickets-and-prs-are-actually-for.mddocs/seo-strategy/citation-deltas/rethinking-systems-in-the-agentic-age.mdSummary of proposed citations
The single "no source found" is the
superpowers plugin / writing-skillsreference inwhere-agentic-patterns-actually-live: most likelygithub.com/obra/superpowers, but flagged for Julian to disambiguate his preferred surface (repo root vs. specific skill subdirectory vs. plugin-marketplace listing).Notable verified sources
docs.claude.com/en/docs/claude-code/*paths now 301-redirect tocode.claude.com/docs/en/*; deltas point to the final destinations)modelcontextprotocol.io)github.com/anthropics/claude-cookbooks)Test plan
pnpm lintpasses (warnings only, all pre-existing)pnpm test:unitpasses (525/525)pnpm typecheckpassesCloses #392