Skip to content

comparisons.md

Latest commit

 

History

History
116 lines (94 loc) · 7.38 KB

comparisons.md

File metadata and controls

116 lines (94 loc) · 7.38 KB
Raw

Comparison architecture

A comparison explains which Skill fits a concrete task. ADR-0009 records the pillar decision.

Ownership and topology

flowchart LR
  Research[skilld discovery and pinned source review] --> Article[Comparison Markdown]
  Article --> Schema[Evidence schema]
  Schema --> Collection[Marketing content collection]
  Collection --> Route[Explicit comparison route]
  Route --> Renderer[MarketingArticle]
  Renderer --> Run[Copy run command]
  Gate[Page admissions] --> Robots[Page robots]
  Gate --> Sitemap[Pages sitemap exclusions]
Loading
Concern Owner
Article and source ledger layers/marketing/content/comparisons/<slug>.md
Required evidence parser layers/marketing/shared/comparison.ts
Collection schema layers/marketing/content.config.ts
Route layers/marketing/app/pages/compare/<slug>.vue
Renderer and metadata Existing MarketingArticle and useMarketingArticle
Indexing and cull page-admissions.ts and discovered comparison routes in nuxt.config.ts

No live registry join is needed to render an article. If future articles need registry data, read it over HTTP. Keep prose, evidence, and selection reasons in the article, outside registry rows. ComparisonSkillCard renders the shared SkillCard from the article's editorial snapshot. Keep its exact Skill route and pinned source beside the overview. Omit live counts and freshness. Article authorGithub supplies an optional avatar through the existing same-origin image proxy.

Authoring contract

  1. Name one reader decision and one target query. State the inclusion and exclusion rules.
  2. Discover candidates through skilld search <query> --json. Use returned selectors without guessing.
  3. Read each candidate with skilld run <selector> --json and named supporting files when needed.
  4. Record the exact source commit and SKILL.md link. Preserve failures and private research in scratch.
  5. If delivery fails, inspect pinned public source independently. Describe the method without claiming a successful run.
  6. If checks block delivery, keep that constraint beside the candidate. Do not suggest bypassing checks.
  7. Filter candidates before writing. Keep meaningful choices; retain the wider source ledger in the work brief.
  8. Introduce the choice, then describe each featured Skill with its card before the decision table and supporting sections.
  9. Review material claims against the sources, then review voice against COPY and GLOSSARY.

Frontmatter requires targetQuery, reviewedAt, reviewDueAt, scope, methodology, disclosure, and sources. Each source records selector, revision, and url. The URL names the same repository and commit. Use methodology: source-review. Do not infer output quality from instruction length, stars, or rule counts.

Visible content carries the review date, selection scope, method, limitations, and relevant relationships. Use agent authorship for agent-written work. Never attribute the article to Harlan without approval. Source links remain one click away. Link the writing track for broader discovery. Wrap each table in a focusable .comparison-table region with a specific accessible label. Keep horizontal scrolling inside that region. Preserve native table semantics.

Internal links

Link a comparison from the relevant track, its featured Skill pages, and one relevant homepage section. Use descriptive anchors that name the choice. Avoid a global footer link or links on unrelated Skills. Link back to the compared Skill pages and the broader track, beside the relevant choice. Keep pinned GitHub sources linked alongside the source review.

shared/comparison-navigation.ts owns the static public link and exact featured Skill identities. It contains navigation metadata only, with no collection reads or server utilities. Registry and app consumers import no marketing code. Any future live article reads must use HTTP. When retiring a comparison, remove its navigation declaration and all referring links with the route.

Comparison conventions

Lead with conditional choices. Compare the same decision dimensions across candidates. Describe partial or unknown coverage in words. Avoid decorative checkmarks and a universal winner. Include disadvantages for a preferred candidate. Separate related forks from independent evidence. Distinguish source declarations, observed behavior, and editorial opinion.

Keep factual meaning, conditions, citations, and deliberate voice as common evaluation criteria. Do not equate a Skill's internal score with detector accuracy or benchmark performance. No detector-evasion promise, invented testimonial, fabricated result, paid placement, or safety claim. Do not add Product, Review, or rating schema without evidence that supports those entities and properties.

These conventions adapt the alternatives-pages Skill. It was discovered and read through skilld with verified provenance. Its default commercial CTA and keep-every-page advice yield to VISION's run action and cull rule. Google's reviews guidance favors original research and analysis. Google's helpful-content guidance asks authors to explain how content was produced. These are quality principles, not a promise of ranking.

Admission, refresh, and cull

Default every new comparison to noindex. Add no admission based on estimated demand. To admit it, record measured demand or its named experiment role in PAGE_ADMISSIONS. Use the existing bar in that file, plus the editorial contract above. The initial query is best humanizer skill for claude, estimated at 30 US monthly searches on 5 October 2026. It misses the existing 100-search bar. The source ledger records keyword and selection evidence. A higher-volume repository-name query does not override the competitor-brand exclusion. Harlan admitted this one page as experiment F on 5 October 2026. Its original source review and contextual links share the 11 November recovery gate. Read coverage and relevant query impressions. Retain it only if indexed with relevant search impressions. Otherwise remove the admission. Future comparison pages keep the default gate.

Review sources at least quarterly, and sooner after a material source change or correction. Update reviewedAt only after reading the relevant sources again. Set reviewDueAt to the next editorial review date. It creates no automation or promise of a scheduled task. Refresh affected claims, source commits, language support, required files, and command availability together.

If an admitted article loses its evidence or task value, remove its admission first. If the article is retired, remove the route and content. Redirect only when a real equivalent exists; otherwise return 410. Do not leave obsolete comparison matrices indexed for URL volume.

Verification

Check schema rejection paths, robots, sitemap exclusion, and missing-content 404. Check SSR content, canonical URL, and the copied command in the running page. Check table overflow at 375px and 768px, keyboard access, and both themes. Run the repository checks and published CLI grammar check before submitting the PR.