@damiangilgonzalez/harness 1.3.7

package/skills/api-design/references/versioning-and-evolution.md

@@ -0,0 +1,49 @@
+# Versioning & evolution
+
+Default posture: **evolve additively, version rarely.** A version is a fork of your client base — earn it.
+
+## Breaking vs non-breaking matrix
+
+| Change | Breaking? | Notes |
+|---|---|---|
+| Add a new optional response field | No | clients ignore unknown fields if you told them to |
+| Add a new endpoint | No | nothing existing changes |
+| Add a new optional query/body param | No | old requests still valid |
+| Add a new enum value | No* | *only if clients were told to tolerate unknown values; otherwise breaking |
+| Loosen a validation rule | No | previously-rejected input now accepted |
+| Remove or rename a field | **Yes** | clients reading it break |
+| Change a field's type or format | **Yes** | `string` → `object`, date format change, etc. |
+| Make an optional field required | **Yes** | old requests start failing |
+| Tighten validation (narrower accepted range) | **Yes** | previously-valid input now rejected |
+| Change a status code for a case | **Yes** | client branching breaks |
+| Change an error `type` URI for a case | **Yes** | clients branch on `type` |
+| Change pagination/cursor semantics | **Yes** | in-flight pagination breaks |
+
+Design hint: tell clients up front to **ignore unknown fields and tolerate unknown enum values** ("must-ignore" / robustness rule). That single contract clause turns many would-be breaking changes into additive ones.
+
+## Three versioning mechanisms
+
+| Mechanism | Example | Pros | Cons |
+|---|---|---|---|
+| **URL path** | `/v1/projects` | visible, cacheable, browser-testable, expected by most clients | version leaks into every URL; "v" is coarse-grained |
+| **Header / media type** | `Accept: application/vnd.acme.v2+json` | clean URLs, content-negotiated | harder to test/cache, easy to forget, opaque to humans |
+| **Query param** | `/projects?version=2` | trivial to add | pollutes URLs, easy to omit, muddies caching |
+
+**Default to URL path for public APIs.** Reserve header/media-type versioning for internal APIs where tooling controls the header. Don't mix mechanisms.
+
+## Deprecation & sunset workflow
+
+1. Ship the successor (new field/endpoint/version) additively.
+2. Mark the old surface deprecated in responses:
+
+```http
+Deprecation: true
+Sunset: Sat, 31 Oct 2026 23:59:59 GMT
+Link: <https://api.acme.com/v2/projects>; rel="successor-version"
+```
+
+3. Document the migration and the sunset date; notify known integrators.
+4. Hold the deprecated surface working until the `Sunset` date — give clients real time (months, not days, for public APIs).
+5. After sunset, return `410 Gone` for the removed surface (not `404`) so clients learn it was intentional.
+
+Keep the deprecation window generous and the messaging programmatic — clients should learn from headers, not from breakage.

package/skills/api-design/scripts/verify.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# verify.sh — read-only check of an API-design artifact (OpenAPI 3.1 spec).
+#
+# The api-design skill emits its contract as an OpenAPI document. This script
+# finds candidate spec files under a target dir, validates they parse and carry
+# the required OpenAPI keys, and emits non-fatal warnings for the design
+# anti-patterns it can detect statically. It never writes anything.
+#
+# Usage:   verify.sh [TARGET_DIR]   (default: current directory)
+# Exit:    0  no spec found (soft-pass) OR all found specs valid
+#          1  a spec file is present but invalid/unparseable
+#
+# Soft-pass on a clean/empty target: a design may live only in a doc.
+
+set -uo pipefail
+
+TARGET="${1:-.}"
+fail=0
+
+note()  { printf '  - %s\n' "$1"; }
+warn()  { printf '  ! %s\n' "$1"; }
+
+if [ ! -d "$TARGET" ]; then
+  echo "verify(api-design): target '$TARGET' is not a directory — nothing to check."
+  exit 0
+fi
+
+# Collect candidate OpenAPI files (read-only). Tolerate no matches.
+# Portable to bash 3.2 (macOS default): no mapfile; newline-delimited list.
+specs=()
+while IFS= read -r f; do
+  [ -n "$f" ] && specs+=("$f")
+done < <(
+  find "$TARGET" \
+    \( -name 'openapi.yaml' -o -name 'openapi.yml' -o -name 'openapi.json' \
+       -o -name '*.openapi.yaml' -o -name '*.openapi.yml' -o -name '*.openapi.json' \) \
+    -type f 2>/dev/null
+)
+
+if [ "${#specs[@]}" -eq 0 ]; then
+  echo "verify(api-design): no OpenAPI spec found under '$TARGET' — soft-pass (design may be in-doc only)."
+  exit 0
+fi
+
+# Choose a linter if available; else fall back to a structural check.
+LINTER=""
+if command -v redocly >/dev/null 2>&1; then
+  LINTER="redocly"
+elif command -v spectral >/dev/null 2>&1; then
+  LINTER="spectral"
+fi
+
+# Structural fallback: parse + required keys, using whatever is on PATH.
+parse_check() {
+  local f="$1"
+  case "$f" in
+    *.json)
+      if command -v jq >/dev/null 2>&1; then
+        jq -e 'has("openapi") and has("info") and has("paths")' "$f" >/dev/null 2>&1
+        return $?
+      fi
+      ;;
+    *.yaml|*.yml)
+      if command -v python3 >/dev/null 2>&1; then
+        python3 - "$f" <<'PY' >/dev/null 2>&1
+import sys
+try:
+    import yaml
+except Exception:
+    sys.exit(2)  # no yaml lib -> can't check, treat as inconclusive
+with open(sys.argv[1]) as fh:
+    d = yaml.safe_load(fh)
+sys.exit(0 if isinstance(d, dict) and all(k in d for k in ("openapi", "info", "paths")) else 1)
+PY
+        local rc=$?
+        [ "$rc" -eq 2 ] && return 3   # inconclusive
+        return $rc
+      fi
+      ;;
+  esac
+  return 3  # inconclusive: no suitable parser on PATH
+}
+
+# Static anti-pattern warnings (grep-based, never fatal).
+antipattern_scan() {
+  local f="$1"
+  if grep -Eiq '"?/[A-Za-z0-9_]*(get|create|update|delete|fetch|list)[A-Za-z0-9_]*"?[[:space:]]*:' "$f"; then
+    warn "verb-like path segment(s) detected — paths should be nouns; HTTP methods are the verbs."
+  fi
+  if grep -Eq '(/[A-Za-z0-9_/{}]*)+[[:space:]]*:' "$f" && ! grep -Eiq 'cursor|limit|offset|first|after|page' "$f"; then
+    warn "no pagination params (cursor/limit/offset) found — list endpoints should paginate."
+  fi
+  if ! grep -Eiq 'problem\+json|"4[0-9][0-9]"|default[[:space:]]*:' "$f"; then
+    warn "no 4xx / default error responses found — every operation should define an error response (RFC 9457)."
+  fi
+}
+
+echo "verify(api-design): checking ${#specs[@]} spec file(s) under '$TARGET'"
+[ -n "$LINTER" ] && echo "  using linter: $LINTER"
+
+for f in "${specs[@]}"; do
+  echo "* $f"
+  ok=1
+  if [ -n "$LINTER" ]; then
+    if [ "$LINTER" = "redocly" ]; then
+      redocly lint "$f" >/dev/null 2>&1 || ok=0
+    else
+      spectral lint "$f" >/dev/null 2>&1 || ok=0
+    fi
+    if [ "$ok" -eq 0 ]; then
+      # Linter unhappy: confirm with structural parse before failing hard.
+      parse_check "$f"; pc=$?
+      if [ "$pc" -eq 0 ]; then
+        warn "$LINTER reported issues but the spec parses and has required keys — review lint output."
+      else
+        note "spec is invalid per $LINTER."
+        fail=1
+        continue
+      fi
+    fi
+  else
+    parse_check "$f"; pc=$?
+    case "$pc" in
+      0) : ;;  # valid
+      3) warn "no parser on PATH (jq/python3+pyyaml) — skipped structural validation." ;;
+      *) note "spec does not parse or is missing required keys (openapi/info/paths)."; fail=1; continue ;;
+    esac
+  fi
+  antipattern_scan "$f"
+done
+
+if [ "$fail" -ne 0 ]; then
+  echo "verify(api-design): FAIL — one or more specs are invalid."
+  exit 1
+fi
+
+echo "verify(api-design): OK (warnings, if any, are advisory)."
+exit 0

package/skills/article-writing/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: article-writing
+description: "Use when writing one long-form article end to end — answer-first lede, question-shaped headings, plus its on-page surface (title, meta, slug, FAQ, Article/FAQPage JSON-LD) — or fixing a draft that buries the answer or reads AI-padded. NOT keyword research or topic selection (that is `seo-geo`), NOT the editorial calendar (that is `content-engine`)."
+tags: [article, blog, long-form, seo-writing, geo, on-page, eeat, copywriting]
+recommends: [seo-geo, content-engine, brand-voice, landing-copy, technical-writing, case-studies]
+origin: risco
+---
+
+# Article writing
+
+Draft one long-form article end to end: the prose **and** the on-page surface that ships with it — answer-first lede, question-shaped headings, title tag, meta description, slug, FAQ block, and the JSON-LD that makes the piece machine-readable.
+
+You own a single finished article. You do not pick the topic, build the calendar, or define the house voice — those are siblings below.
+
+## When NOT to use
+
+| You want… | Go to |
+| --- | --- |
+| Keyword research, SERP tracking, technical SEO, deciding which topics to target | [`../seo-geo/SKILL.md`](../seo-geo/SKILL.md) |
+| Editorial calendar, topic-cluster plan, pipeline across many pieces | [`../content-engine/SKILL.md`](../content-engine/SKILL.md) |
+| The reusable brand tone-of-voice spec the article is written in | [`../brand-voice/SKILL.md`](../brand-voice/SKILL.md) |
+| A conversion landing or sales page (hero, offer, CTA) | [`../landing-copy/SKILL.md`](../landing-copy/SKILL.md) |
+| An email newsletter issue (subject line, send) | [`../newsletter/SKILL.md`](../newsletter/SKILL.md) |
+| Product docs, API reference, software how-tos | [`../technical-writing/SKILL.md`](../technical-writing/SKILL.md) |
+| A customer outcome story / narrative | [`../case-studies/SKILL.md`](../case-studies/SKILL.md) |
+
+Rule: if the deliverable is not *one publishable article*, you are in the wrong skill.
+
+## Start from intent, not a word count
+
+Before you write a sentence, read the top of the SERP for the target query. Name two things: the **dominant intent** (informational, transactional, comparison, navigational) and the **winning format** Google already rewards (listicle, step guide, definition + table, comparison). Match that format — fighting the shape Google already chose loses.
+
+Then set depth from intent, not from a number you were handed. The first-page Google average is ~1,447 words across 11.8M results (Backlinko) — a *descriptive average*, never a target. Thoroughness and intent satisfaction rank, not length.
+
+| Intent | Typical depth | Shape |
+| --- | --- | --- |
+| Simple how-to / quick answer | 400–800 words | Direct answer, short steps, one image |
+| Standard informational post | 1,500–2,000 words | Answer-first lede + question H2s |
+| Comprehensive guide | 1,700–2,500 words | Full subtopic coverage, tables, FAQ |
+| Pillar page | 2,500–5,000 words | Hub with two-way cluster links |
+
+Why: padding a 600-word answer to 2,000 to "look thorough" dilutes it and reads as filler. Cutting a guide to 800 words leaves the query half-answered. Length follows the question.
+
+## The answer-first lede
+
+The first ~200 words must directly and completely answer the primary query. Lead with the answer (TL;DR-first / inverted pyramid), then expand. This is the structure that wins featured snippets and AI Overview citations — and with zero-click hitting ~60% of searches (2024) and AI Overviews appearing in ~13% of queries (May 2025), being the extracted answer matters more than the click.
+
+```markdown
+<!-- Bad: warms up for three paragraphs before answering -->
+## Should you compost in an apartment?
+Composting has become increasingly popular in recent years as more people
+look for sustainable lifestyle choices. Many city dwellers assume they can't
+participate because of limited space. But is that really true? Let's explore
+the fascinating world of urban composting and find out together.
+```
+
+```markdown
+<!-- Good: answers in the first two sentences, then expands -->
+## Can you compost in an apartment?
+Yes — a sealed countertop bokashi bin or a small worm bin (vermicomposting)
+lets you compost food scraps in a flat with no yard and no smell. Bokashi
+ferments scraps in ~2 weeks; a worm bin yields finished compost in 3–6 months.
+Here is how to choose between them and set one up in a 60×40 cm footprint.
+```
+
+If the query is a question, the H1 or first H2 should *be* that question and the next sentence should answer it. Worked lede examples are in [`references/on-page-seo.md`](references/on-page-seo.md).
+
+## Outline as a question map
+
+Build the skeleton from real subtopics, not from what you feel like writing.
+
+- **One H1**, matching the primary query or its close paraphrase.
+- **H2/H3 are questions or named subtopics** that mirror the SERP's "People also ask", related searches, and the headings competitors share — plus the gaps they all miss (that gap is your edge).
+- **One idea per heading.** A heading that needs an "and" is two headings.
+- Headings are subtopics, not slogans: `## How much does a standing desk cost?` not `## The Price Question`.
+
+Why question-shaped headings: only ~38% of pages cited in AI Overviews rank top-10, so clean, extractable, question→answer structure can win citations without traditional authority. Make every section answerable on its own.
+
+## Drafting for depth and E-E-A-T
+
+Google does **not** penalize AI-assisted content as such. It penalizes *scaled content abuse* — high-volume, no-editorial-review, thin, no-first-hand-experience pages. The March 2026 core update named scaled content abuse a primary target; offending sites saw 50–80% traffic drops. The defense is not avoiding AI; it is genuine value, depth, and human review.
+
+So every draft earns its keep with E-E-A-T (Experience, Expertise, Authoritativeness, **Trust** — Trust is the load-bearing member):
+
+- **First-hand experience** — a thing you tested, measured, or saw. "We ran the worm bin for 90 days and weighed the output" beats "worm bins are effective".
+- **Original data or insight** — a number, comparison, or angle not already on page one.
+- **Credible cited sources** for claims you did not generate yourself — link them inline.
+- **Clear authorship** — a named author with relevant standing, not "admin".
+- **Match intent over keyword density.** Answer the question fully; the keywords fall out naturally. Never stuff.
+
+Run a human-review pass before ship. If nothing in the draft could only have been written by someone who actually knows the topic, it is thin — add experience or do not publish.
+
+## The on-page surface
+
+Every article ships with these. Keep them in the file's front-matter or a clearly labelled block so [`scripts/verify.sh`](scripts/verify.sh) can lint them.
+
+- **Title tag**: 50–60 characters / under ~580–600 px desktop (~480 px mobile). Put the primary keyword in the first ~30–35 characters. Titles of 51–55 chars are rewritten by Google least often.
+- **Meta description**: 140–160 characters (desktop ~920 px ≈ 158 chars; mobile cuts at ~120). One to three sentences, lead with the value. It does not rank, but it drives CTR and is often the snippet AI engines echo.
+- **H1**: exactly one, matching the query.
+- **Slug**: short, lowercase, hyphenated, keyword-bearing, no stop-word noise — `/compost-in-apartment` not `/how-to-start-composting-in-your-apartment-today`.
+- **FAQ block**: 3–6 real questions from "People also ask", each answered in 2–4 sentences.
+
+Full pixel/char tables, slug rules, and copy-ready `Article`/`BlogPosting` + `FAQPage` JSON-LD (JSON-LD only — never microdata) live in [`references/on-page-seo.md`](references/on-page-seo.md). The JSON-LD must describe what is actually on the page; schema that does not match visible content is a quality flag, not a win.
+
+## Internal links and topical authority
+
+Place **3–5 contextual internal links** in the body of a standard article (more only for a long-form pillar). Rules:
+
+- **Descriptive anchor text** — `worm bin setup guide`, never `click here` or a bare URL.
+- Keep priority pages within ~3 clicks of the post.
+- For a pillar, link **two ways**: pillar → each cluster article and each cluster article → pillar. That two-way map is the topical-authority signal AI engines read.
+
+You insert the link *slots* and anchors that fit this article. Deciding the *cluster structure* — which pillar owns which clusters across the site — is [`../content-engine/SKILL.md`](../content-engine/SKILL.md)'s job, not yours.
+
+## Cut the AI tells and the fluff
+
+Do one ruthless pass: **delete every sentence that adds no fact.** If a sentence could sit in any article on any topic, it is filler.
+
+Banned on sight (short sample): "In today's fast-paced world", "It's important to note that", "When it comes to", "Let's dive in", "the world of X", "navigating the landscape of", "unlock the power of", "in conclusion". The full banlist with Bad→Good rewrites and the depth self-review is in [`references/ai-tell-banlist.md`](references/ai-tell-banlist.md) — and that file is the single source `verify.sh` greps against.
+
+```markdown
+<!-- Bad: 28 words, zero facts -->
+In today's fast-paced world, it's important to note that choosing the right
+standing desk can really make a difference when it comes to your health.
+```
+
+```markdown
+<!-- Good: 19 words, three facts -->
+A standing desk adjustable from 70–120 cm fits users 1.5–2.0 m tall and cuts
+the lower-back load reported across sit-all-day workdays.
+```
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+| --- | --- | --- |
+| Padding to hit a word count | Dilutes the answer; reads as filler | Set depth from intent; ~1,447w is an average, not a target |
+| Intro that warms up before answering | Loses snippets, AI Overviews, and ~60% zero-click readers | Answer the query in the first ~200 words |
+| Keyword stuffing for density | Reads spammy; Google rewards intent match, not density | Answer fully; keywords fall out naturally |
+| H2s that are slogans, not subtopics | Not extractable; misses People-also-ask citations | Question-shaped, one idea per heading |
+| No named author or cited sources | Thin E-E-A-T; vulnerable in core updates | Add first-hand experience, data, citations, an author |
+| FAQ with no FAQPage schema (or schema ≠ visible content) | Not machine-readable; mismatched schema is a quality flag | Ship matching `FAQPage` JSON-LD describing on-page Q&As |
+| Generic AI-tell prose | Flagged as scaled, low-value content | Run the banlist + delete-no-fact-sentence pass |
+| Ignoring the SERP's winning format | Fights the shape Google already rewards | Match the dominant format, then beat it on depth |
+
+## Ship checklist
+
+Restating the gates `verify.sh` enforces, for the human review:
+
+- [ ] Answer-first lede — primary query fully answered in first ~200 words
+- [ ] Exactly one H1; at least two question-shaped H2s
+- [ ] Title 50–60 chars (keyword early); meta 140–160 chars
+- [ ] JSON-LD present with `@type` `Article`/`BlogPosting`; `FAQPage` too if an FAQ section exists
+- [ ] At least one contextual internal-link slot with a descriptive anchor (target 3–5)
+- [ ] AI-tell / fluff banlist scan is clean
+- [ ] Depth matches intent; first-hand experience or original data present; author + sources named
+
+Run `scripts/verify.sh path/to/article.md`. It is a lint of structure and banned phrasing — it does not judge whether the content is *good*. That is the capability eval's job, and yours.

package/skills/article-writing/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — article-writing
+
+`cases.yaml` is read by the repo's standard eval harness. The `should_trigger` and `should_not_trigger` cases test routing and description discrimination: each `should_trigger` prompt must load this skill (including the non-obvious answer-first-lede and the Catalan cases), and each `should_not_trigger` prompt must route to the named sibling (`seo-geo`, `content-engine`, `brand-voice`, `landing-copy`) instead — that confirms the boundary in the description holds. The single `capability` case is graded by rubric, not pass/fail automation: a grader (human or model) asks the skill to draft the standing-desk article and checks the produced markdown against each `must_include` item, then runs `scripts/verify.sh path/to/draft.md` to confirm the structural and banlist gates pass. There is no automated scoring beyond the harness and that verify lint; run it with the repo's usual eval runner.

package/skills/article-writing/evals/cases.yaml

@@ -0,0 +1,47 @@
+skill: article-writing
+
+# Prompts that MUST load `article-writing`. The skill owns the DRAFT and the
+# on-page surface of ONE long-form article — not topic selection, not the
+# calendar, not the voice spec, not landing pages.
+should_trigger:
+  - prompt: "Write a 1,500-word blog post on how to compost in an apartment."
+    why: "Core job — drafting one long-form article from a topic at a set depth."
+  - prompt: "Rewrite this intro so the answer comes first instead of warming up for three paragraphs."
+    why: "Non-obvious — the answer-first lede is this skill's signature; no SEO keyword language but squarely in scope."
+  - prompt: "Add an FAQ section and FAQPage schema to my published article."
+    why: "On-page surface ownership — FAQ block + Article/FAQPage JSON-LD ship with the piece."
+  - prompt: "Escriu un article de blog sobre teletreball i productivitat optimitzat per SEO."
+    why: "Catalan phrasing for drafting an SEO-optimized blog article — same core job in another language."
+  - prompt: "This draft reads like AI wrote it and it's padded — tighten it to the depth the topic needs."
+    why: "Fluff/AI-tell + intent-depth pass; no explicit 'article' word but the deliverable is one tightened draft."
+  - prompt: "Restructure this rambling post into clear question-shaped H2s and H3s."
+    why: "Non-obvious — heading hierarchy as a question map is owned here, framed as editing not writing."
+
+# Prompts that must NOT load `article-writing` — each routes to a real sibling.
+should_not_trigger:
+  - prompt: "Find the best keywords and check which topics can actually rank for my site."
+    route_to: seo-geo
+    why: "Keyword research and topic/strategy selection — deciding WHAT to write, not drafting it."
+  - prompt: "Build me a 3-month editorial calendar with topic clusters."
+    route_to: content-engine
+    why: "Calendar and pipeline across many pieces, not the draft of a single article."
+  - prompt: "Define our brand tone of voice and a reusable writing style guide."
+    route_to: brand-voice
+    why: "The reusable voice spec the article is written IN, not one article."
+  - prompt: "Write the homepage hero and CTA section to convert visitors."
+    route_to: landing-copy
+    why: "A conversion landing page (hero/offer/CTA), not a long-form article."
+
+# At least one capability scenario, graded by rubric against a produced draft.
+capability:
+  - scenario: "Draft a ~1,500-word article from the target query 'how to choose a standing desk', producing the prose plus its full on-page surface."
+    must_include:
+      - "Answer-first lede that fully answers the query in the first ~200 words (best desk type + the deciding specs), before any windup."
+      - "Question-shaped H2/H3 hierarchy with exactly one H1 matching the query."
+      - "Title tag 50-60 chars with the primary keyword in the first ~30-35 chars."
+      - "Meta description 140-160 chars, value-first."
+      - "A short, keyword-bearing slug."
+      - "An FAQ block of real questions plus matching Article/BlogPosting + FAQPage JSON-LD (JSON-LD only) describing the visible content."
+      - "3-5 contextual internal-link slots with descriptive anchor text (not 'click here')."
+      - "Depth matched to informational intent (~1,500-2,000 words) with no AI-tell padding — passes the banlist."
+      - "An E-E-A-T signal: named author and/or cited credible sources, plus first-hand experience or original data."

package/skills/article-writing/references/ai-tell-banlist.md

@@ -0,0 +1,114 @@
+# AI-tell banlist + E-E-A-T self-review
+
+The single source of truth for the fluff/AI-tell phrases. `scripts/verify.sh` greps the draft against the fenced `BANLIST` block below — keep **one phrase per line**, lowercase, so the script can read it. The padding patterns and the E-E-A-T self-review are for the human/agent pass; the script only handles the literal phrase grep.
+
+## BANLIST
+
+These are case-insensitive substrings. A match is a fail — rewrite or delete the sentence.
+
+```text
+in today's fast-paced world
+in today's digital age
+in the world of
+when it comes to
+it's important to note that
+it's worth noting that
+it is worth noting
+needless to say
+at the end of the day
+let's dive in
+let's dive into
+let's explore
+dive deep into
+navigating the landscape
+navigating the world of
+the ever-evolving landscape
+unlock the power of
+unleash the power of
+unlock the potential
+harness the power of
+take your x to the next level
+in conclusion
+in summary,
+when all is said and done
+a game-changer
+game changer in the
+the key takeaway is
+without further ado
+look no further
+whether you're a beginner or
+this comprehensive guide
+in this article, we will
+buckle up
+rest assured
+it goes without saying
+plays a crucial role in
+plays a vital role
+a testament to
+embark on a journey
+the realm of
+```
+
+## Padding patterns (rewrite, not just delete)
+
+These are not single phrases the grep catches; they are shapes. Spot them in review.
+
+| Pattern | Tell | Fix |
+| --- | --- | --- |
+| Restating the question as a paragraph before answering | "You might be wondering whether…" | Cut it; answer directly |
+| Listing what the article *will* cover | "In this guide we'll look at A, B, and C" | Delete; let the headings do it |
+| Hedged non-claims | "can potentially help in some cases" | State the claim with a condition and a number |
+| Empty transitions | "Now that we've covered X, let's move on to Y" | Delete; the next H2 is the transition |
+| Definition padding for a known term | "SEO, which stands for search engine optimization, is…" | Define only if the audience needs it |
+| Symmetry filler | "On the one hand… on the other hand…" with no real tension | Pick the answer; note the real trade-off |
+| Summary that repeats the body verbatim | A conclusion restating each H2 | Replace with a next step or a decision rule |
+
+## The delete-no-fact pass
+
+Read each sentence and ask: **does this add a fact, a number, a step, or a named example?** If no, delete it. A 1,500-word draft that survives this pass beats a 2,500-word draft that does not.
+
+Concrete test — every paragraph should contain at least one of: a number, a proper noun, a measured result, a named tool, a date, a specific step, or a cited source. A paragraph of pure adjectives is filler.
+
+## Bad → Good rewrites
+
+```markdown
+<!-- Bad -->
+When it comes to choosing a standing desk, it's important to note that there
+are many factors to consider. In today's world, ergonomics plays a crucial
+role in our daily lives, so let's dive in and explore your options.
+```
+
+```markdown
+<!-- Good -->
+Choose a standing desk on three specs: height range (match your standing elbow
+height, usually 95–120 cm), motor (dual beats single for stability), and lift
+capacity (100 kg+ if you mount a monitor arm and a heavy display).
+```
+
+```markdown
+<!-- Bad -->
+Oat milk has become increasingly popular as a game-changer in the world of
+dairy alternatives. Without further ado, let's unlock the secrets of why so
+many people are making the switch.
+```
+
+```markdown
+<!-- Good -->
+Oat milk overtook almond as the top US plant milk by 2022 sales. It is creamier
+because oats release beta-glucan; the trade-off is more carbs (~16 g/cup) than
+soy or almond, which matters if you watch blood sugar.
+```
+
+## E-E-A-T self-review (human/agent pass, not scripted)
+
+Before ship, answer each. A "no" is a gap to fix, not a nuance to wave past.
+
+- [ ] **Experience** — does the piece include something only someone who did/tested/used the thing would know?
+- [ ] **Expertise** — are claims accurate, current, and at the right technical level for the audience?
+- [ ] **Authoritativeness** — is there a named author with a bio and relevant standing (not "admin")?
+- [ ] **Trust** — are non-obvious claims cited to credible sources, linked inline? Is anything misleading?
+- [ ] **Original value** — is there a number, comparison, or angle not already on page one of the SERP?
+- [ ] **Intent match** — does the piece fully answer the query, in the SERP's winning format?
+- [ ] **Human review** — has a person read it end to end and would they put their name on it?
+
+If the draft passes the banlist grep but fails this list, it is structurally clean and substantively thin. Thin content is what the March 2026 scaled-content-abuse target penalizes. Fix the substance before shipping.

package/skills/article-writing/references/on-page-seo.md

@@ -0,0 +1,133 @@
+# On-page SEO — title/meta tables, slug rules, JSON-LD templates
+
+The full pixel/char detail and copy-ready schema the SKILL.md body points to. Every number is sourced and dated in the spec (accessed 2026-06-02).
+
+## Title tag — char and pixel bands
+
+| Metric | Desktop | Mobile |
+| --- | --- | --- |
+| Display ceiling | ~580–600 px | ~480 px |
+| Practical char band | 50–60 chars | shorter; front-load |
+| Rewritten least often | 51–55 chars | — |
+| Keyword position | first ~30–35 chars | first ~30–35 chars |
+
+Notes:
+
+- Google rewrites titles ~33–40% of the time overall; the 51–55 char band is rewritten *least*. Stay in it.
+- Pixel width varies by character (an `m` is wide, an `i` is narrow), so the char band is a proxy — if the title is title-case with many wide caps, lean toward 50–55.
+- Front-load the primary keyword. A title that buries the keyword past char 35 risks truncation cutting it off on mobile.
+- One title per page. The `<title>` tag and the on-page H1 may differ; the H1 can be longer and more human.
+
+## Meta description — char and pixel bands
+
+| Metric | Desktop | Mobile |
+| --- | --- | --- |
+| Display ceiling | ~920 px ≈ 158 chars | ~680 px ≈ 120 chars |
+| Practical char band | 140–160 chars | front-load value in first ~120 |
+| Sentences | 1–3 | 1–2 |
+
+Notes:
+
+- The meta description does **not** rank directly, but it drives click-through and is frequently the snippet AI engines echo verbatim. Treat it as ad copy for the result.
+- Lead with the value/answer, not a windup. Include the primary keyword once, naturally (Google bolds matched terms).
+- If you write past 160 chars, write so the first ~120 stand alone — that is what mobile shows.
+
+## Slug rules
+
+- Lowercase, words hyphen-separated, ASCII.
+- 3–5 meaningful words; drop stop words (`the`, `a`, `to`, `your`, `how`) unless they carry meaning.
+- Keyword-bearing and stable — do not change a published slug without a 301 redirect.
+- Bad: `/how-to-start-composting-in-your-apartment-today` → Good: `/compost-in-apartment`.
+- No dates or volatile params in evergreen slugs (`/standing-desk-guide`, not `/2026/03/standing-desk-guide-v2`).
+
+## Worked answer-first ledes
+
+Pattern: **state the answer in sentence 1–2, qualify in 3–4, signpost what follows.**
+
+Query: *how to choose a standing desk*
+
+> The best standing desk for most people is an electric sit-stand desk with a 70–120 cm height range, a dual motor, and at least 100 kg lift capacity. Pick by adjustment range (match your height), stability at full extension, and warranty (aim 5+ years on the frame). Below: how to size it, what specs actually matter, and the mistakes that waste money.
+
+Query: *is oat milk good for you*
+
+> Oat milk is a reasonable dairy alternative: ~120 kcal and 3 g protein per cup, naturally low in saturated fat, and usually fortified with calcium and B12. It is not ideal if you need high protein or are watching blood sugar (it is higher in carbs than soy or almond milk). Here is how it compares cup-for-cup and who should pick something else.
+
+Both answer the query before the reader scrolls — the requirement for featured snippets and AI Overview extraction.
+
+## JSON-LD templates (JSON-LD only — never microdata)
+
+Embed in a `<script type="application/ld+json">` block in the page `<head>` or body. Use **one** article type per page. The schema must describe what is actually visible on the page.
+
+### Article / BlogPosting
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "BlogPosting",
+  "headline": "How to Choose a Standing Desk: Specs That Matter",
+  "description": "A spec-by-spec guide to choosing a sit-stand desk: height range, motor, lift capacity, stability, and warranty.",
+  "image": ["https://example.com/img/standing-desk-guide.jpg"],
+  "datePublished": "2026-06-02T08:00:00+01:00",
+  "dateModified": "2026-06-02T08:00:00+01:00",
+  "author": {
+    "@type": "Person",
+    "name": "Jordi Vila",
+    "url": "https://example.com/author/jordi-vila",
+    "jobTitle": "Ergonomics editor"
+  },
+  "publisher": {
+    "@type": "Organization",
+    "name": "Example Media",
+    "logo": {
+      "@type": "ImageObject",
+      "url": "https://example.com/logo.png"
+    }
+  },
+  "mainEntityOfPage": {
+    "@type": "WebPage",
+    "@id": "https://example.com/standing-desk-guide"
+  }
+}
+```
+
+Use `Article` for general/news, `BlogPosting` for blog content. Keep `headline` ≤110 chars. `author` should be a real named `Person` with a `url` to a bio (an E-E-A-T signal). Set `dateModified` honestly on every meaningful edit.
+
+### FAQPage (only when a real FAQ section exists on the page)
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  "mainEntity": [
+    {
+      "@type": "Question",
+      "name": "How much does a good standing desk cost?",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "A reliable electric sit-stand desk runs roughly €300–€600. Below that, motors and stability suffer; above it you pay for materials and brand."
+      }
+    },
+    {
+      "@type": "Question",
+      "name": "Is a standing desk worth it?",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "Yes if you currently sit all day — alternating sitting and standing reduces reported lower-back discomfort. The benefit comes from movement, not standing all day."
+      }
+    }
+  ]
+}
+```
+
+### FAQPage eligibility caveat
+
+Google narrowed FAQ rich-result *display* to authoritative government and health sites in 2023; most sites no longer get the visible FAQ rich result in the SERP. **Still ship the `FAQPage` JSON-LD** — it remains valid structured data that AI engines and assistants parse for extraction, and the Q&A structure is exactly what AI Overviews cite. Every `Question`/`Answer` in the schema must match a visible Q&A on the page; schema-only answers not shown to users are a spam signal.
+
+## On-page surface — assembly order
+
+1. Draft the body and FAQ first.
+2. Write the title from the H1 (tighter, keyword-front-loaded, 50–60 chars).
+3. Write the meta description from the answer-first lede (140–160 chars, value-first).
+4. Generate the slug from the primary keyword.
+5. Build the `Article`/`BlogPosting` JSON-LD; add `FAQPage` only if a visible FAQ exists.
+6. Run `scripts/verify.sh` over the assembled markdown.