docs/blog-std

needs attention

c0719d9 · fullPR #309reviewed 2026-07-14 19:48 UTC0H · 2M · 4L · 2I

The branch

Purpose

Prevent re-litigating the same review findings on every blog post by capturing the durable guidance from the founder review of the first GDMTH pillar post as repo standards

Goal

New Tier-2 rule .claude/rules/blog-authoring.md that auto-loads on blog edits, covering voice, CFE facts, adversarial pass, visuals, screenshots, and brand/accessibility

Sub-goals

SG-1: New .claude/rules/blog-authoring.md with path-scoped frontmatter (blog/**, casos/**, blog components, calendar.yml)
SG-2: content-pipeline.yml prompt updated to read the rule, ground facts in cfe-tariffs skill, run adversarial pass, max-turns 40→60
SG-3: Discovery pointers in CLAUDE.md (SEO/GEO section) and docs/content-strategy.md §2

The changes (whole branch)

What: Added blog-authoring standards rule file (87 lines), updated content-pipeline CI prompt and auto-PR checklist, added cross-references in CLAUDE.md and content-strategy.md
Why: The GDMTH pillar post review surfaced reusable guidance (capacidad/distribución conflation, heliotrope-as-body-text, anonymous screenshots, chart color bugs) that was in danger of being lost; codifying it means the pipeline and future authors start right instead of converging via review
Areas: .claude/rules/blog-authoring.md+87−0.github/workflows/content-pipeline.yml+21−12CLAUDE.md+2−0docs/content-strategy.md+2−0
Blast: 4 files, +112/−12 — docs and CI config only. No runtime code. Rule auto-loads on blog edits; CI pipeline behavior changes slightly (longer prompt, adversarial pass, max-turns 60).

depends-on:#304 depends-on:#222 merge-order-matters

➖typecheck· No code paths touched — typecheck not applicable➖tests· No runtime code added — tests not applicable✅coderabbit· CodeRabbit summary present in PR body: docs/checklist additions noted, no issues flagged

Findings · 8

correctness1

low

max-turns 40→60 adds per-run cost with no guard

.github/workflows/content-pipeline.yml

The 50% turn increase is intentional to accommodate the adversarial pass. No blocking concern, but worth noting for cost-cap awareness alongside the loops caps.mjs pattern. A --max-cost flag or a post-run alert if turns approach 60 would close the loop.

conventions2

medium

Rule references artifacts not yet on main (#304, #222)

.claude/rules/blog-authoring.md

PostImage, the chart component library (BillAnatomyDiagram, TouBlocksChart, etc.), and the cfe-tariffs skill are all referenced as if they exist. They live in PRs #304 and #222. The PR notes the merge order (those first, then this), but the rule has no inline signals — an agent auto-loading this rule today will attempt to use missing components. Adding a one-line note (e.g. '(requires #304 / #222)') next to each forward reference would prevent silent failures during the overlap window.

info

CLAUDE.md pointer covers blog/** but not casos/**

CLAUDE.md

The new CLAUDE.md line says 'auto-loads for apps/web/content/blog/** and the blog components' — it doesn't mention casos/**. Minor coverage gap in the cross-reference, no runtime impact.

improvement5

medium

`casos/**` in path globs but rule has no case-study guidance

.claude/rules/blog-authoring.md:4

apps/web/content/casos/** is in the frontmatter paths, so the rule auto-loads when editing case studies. The rule body is written entirely for pillar/educational posts (GDMTH-style). Case studies likely share most conventions but may differ in structure (client anonymization already covered in §6, but cadence, hero visuals, sources section may not apply). Either add a brief §8 or note that casos follow the same checklist, to avoid agent ambiguity.

low

Adversarial pass framed as 'independent' but runs as inline self-review

.claude/rules/blog-authoring.md:44

§3 says 'run an independent critical read (a subagent works well)' but the pipeline allowedTools is Read,Edit,Write — no Task/Agent tool available for a true subagent spawn. The main agent re-reads its own draft inline. The word 'independent' overstates the separation; 'critical re-read' would be more accurate. Not a blocker — the inline pass is still valuable — but the framing could mislead authors into expecting a genuine dual-agent review.

low

CFE gender agreement rule lacks a wrong/right example

.claude/rules/blog-authoring.md:36

§1 encodes a nuanced Spanish grammar rule ('bare label or with bloque/periodo is masculine (intermedio); with energía/demanda/hora it is feminine (intermedia)'). This was the source of a real GDMTH bug. A side-by-side example (bloque intermedio ✓ / demanda intermedia ✓ / bloque intermedia ✗) would make the rule instantly actionable without requiring linguistic inference.

low

calendar.yml lifecycle not defined in the rule

.claude/rules/blog-authoring.md:18

The non-negotiables say 'before flipping a calendar item to review' but the draft→review→published state machine is not documented here. An author new to the pipeline doesn't know what states exist or how to flip one. A one-line pointer (e.g. 'see apps/web/content/calendar.yml for the draft→review→published lifecycle') would close the gap without adding bulk.

info

Checkbox syntax (- [ ]) in rule file is unambiguous for humans but plain text for agents

.claude/rules/blog-authoring.md:18

GFM task-list checkboxes work well for human reviewers in GitHub but agents reading this file parse them as plain text. An agent could interpret '- [ ]' literally (try to check it off) or just skip the visual cue. Plain imperative bullets would be strictly unambiguous — low priority cosmetic issue.