feat(parsa): seo-foundations covers page types, query families, agent surfaces, and the content handoff - #93
Conversation
… surfaces, and the content handoff Learned from running the skill on discatch (dcouple/discatch PRs #11 and #13). The old skill stopped at "comparison and alternatives pages, then explainers"; it did not say which query families to map, how to read a gap, which page types actually intercept competitor traffic and earn links (alternatives, versus incl. third-party pairs, pricing teardowns, per-source or per-integration pages, mini tools, cookbooks), what an agent-era competitor's discovery kit looks like, or how to hand the inventory to a content pass. It also assumed a live site. Now it is product-agnostic by classifying the product first, lists the eleven query families and the demand signals that work at zero-to-one, states the gap tells and beatability rules, orders page types by value, sets the page rules every money page follows, requires a cold read of the inventory (with the findings that recur), covers non-page discovery surfaces and warns against name squatting, and ends with the writer brief shape for the content pass. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018fH7QAsq3wGqqsEbTmUczU
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: da90e18fcd
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| Run `cold-read` on the inventory with a fresh agent before publishing it. | ||
| The findings that recur: a priority rule that contradicts its rows, two | ||
| competing orderings, status columns that mix access and status, a page | ||
| counted twice, queries with two owners, a page both kept and dropped, new | ||
| page kinds with no template, undefined product terms, citations with bare | ||
| filenames. Fix them before the PR. |
There was a problem hiding this comment.
Running cold-read here and applying its findings before publishing embeds a review-and-mutation feedback loop in the skill. The root CLAUDE.md explicitly requires cold-read to remain a manual, separate skill because review-triggered mutations invalidate downstream work; move this audit to a follow-up step instead of invoking it inline.
Useful? React with 👍 / 👎.
| - Write one brief for the writers that says where the truth lives, the | ||
| rules that never bend (never name a provider, planned means planned, | ||
| concede first, dated numbers, no invented features), the voice, the depth |
There was a problem hiding this comment.
When this handoff follows the alternatives, versus, or pricing pages required above, the universal never name a provider rule can prevent writers from naming the products needed to satisfy the target query and produce the required comparison or pricing table. This appears to be a product-specific restriction; determine it from the repository or brief rather than imposing it on every SEO run.
Useful? React with 👍 / 👎.
| - **Developer tools, infra, open source**: GitHub trending and topics, | ||
| awesome-lists, Reddit niche subs, Hacker News (Show HN and Ask HN), Product | ||
| Hunt, dev communities on X and Bluesky, package registries. Prioritize | ||
| repos with recent commits; discard dead projects. |
There was a problem hiding this comment.
For developer-tool runs, discarding dead projects during discovery removes exactly the products that steps 4 and 5 later require for shutdown and migration queries. A defunct but widely used tool can be the highest-value alternatives target, so retain dead projects as migration candidates while excluding them only from the active-competitor count.
Useful? React with 👍 / 👎.
| **Success criteria**: a checklist with a "what discatch needs" line per | ||
| surface and a sequence tied to the roadmap. |
There was a problem hiding this comment.
For every product other than discatch, this success criterion directs the generated checklist to use the wrong product name, leaking the source project's terminology into an otherwise product-agnostic skill. Substitute the product name discovered in step 1.
Useful? React with 👍 / 👎.
| ```markdown | ||
| # SEO Foundations — [site name] |
There was a problem hiding this comment.
This template emits an em dash, as does the action placeholder at line 381, despite the root CLAUDE.md rule that prohibits em dashes. Because agents will copy this block into generated foundations documents, replace both with permitted punctuation.
Useful? React with 👍 / 👎.
1 participant
Why
I ran
seo-foundationsend to end on a real product (dcouple/discatch, PRs #11 and #13) and the skill left out most of what turned out to matter. The user had to tell the agent, after the fact, that alternatives, versus, mini tools, and cookbooks are the pages that win, that agents find products through registries andllms.txt, and that a no-site product still needs a page plan. The skill should know all of that on its own.What changed
parsa/seo/seo-foundations/SKILL.md, rewritten (180 to 413 lines), product-agnostic:llms.txt,.well-known/mcp.json, OpenAPI, registry entries, CLI, skills), weak spots, structures worth matching, and a corrections table for the repo's own docs.cold-readwith the findings that recur.docs/seo/deliverables.parsa/seo/README.md: the foundations paragraph describes the new scope.Evidence
The discatch run:
docs/seo/keyword-map.md,competitor-map.md,page-inventory.md,discovery-checklist.mdin dcouple/discatch#11, and the templates plus content pass in dcouple/discatch#13. The cold-read findings listed in step 5 are the ones that actually came back on that inventory.🤖 Generated with Claude Code
https://claude.ai/code/session_018fH7QAsq3wGqqsEbTmUczU