revise-content

revise-content — production skill (Phase 11 Wave 1 W-F2)

Section-targeted revise skill. master.xlsx[content_decay] satırından action="revise" alır, R-87 section-targeted diff uygular, R-88 freshness theater preempt eder, R-89 canonical preserve eder, R-103 content version increment eder. READ-ONLY contract: master.xlsx [content_decay] + master_task sheet'lerine YAZMAZ (allowed_writers null + master_task protected_columns 7 alan); sadece outputs/ + _state yazar.

Foundational Principles (Üst-Prensip — Alt-Rule Override Edemez)

Principle 1 — Truth-Verifiable Content (R-27, 3-katman defense)

Tüm content/source/link/data %100 doğru ve kanıtlanabilir; uydurma yasak. Revise context'inde:

• Layer 1 (pre-revise): revise prompt başlangıcında "uydurma yasak" sentinel; revision.template.md truth_verifiable: true field zorunlu.
• Layer 2 (post-revise): fact-check pass — yeni claim'lerin kaynak verify (R-44 source verification + R-105 expert quote).
• Layer 3 (citation): citation enforce — eklenen her stat/quote source URL ile bağlanır.
• Failure mode: P1 fact-check fail → DURUR #7 RED (revize iptal, çıktı discard, dateModified bump YOK).

Principle 2 — Profile-Aware Enforcement (project-config[profile])

Skill behavior project.config.json[profile] enum'una göre değişir. Enum 5-value: e-commerce | ymyl | local-service | b2b-saas | portfolio.

• profile == "ymyl" → counter-argument (R-50) korunur, revize sırasında counter-argument silinemez; byline (R-28) preserve edilmeli, author değişmez (R-89 canonical adjacent).
• profile == "e-commerce" → conversational tone preserve, CTA freshness güncelle.
• profile == "local-service" → location signal preserve (NAP consistency).
• profile == "b2b-saas" → formal tone + diagram/screenshot preserve.
• profile == "portfolio" → showcase entity preserve (project list).

Principle 3 — AI Suistimal Önlemi (Anti-Cheap-Content)

AI'ın doğal cheap content padding davranışını preempt et. Revise context'inde:

• R-88 freshness theater check: dateModified bump + content delta orantılı olmalı; delta == 0 AND claim_delta == 0 AND structure_hash unchanged → RED (sahte tarih güncelleme).
• Section-targeted scope (R-87): full overhaul yasak default; scope=section default; scope=full manuel approve gate (DURUR #5).
• Per-section change quantification: word delta + structure delta + claim delta hesaplama, change_summary.md'ye log.

R-121 Bank Selection Logic (Pre-Revise + Pre-Publish)

Bank entry (R-105 expert quote / R-114 original research / R-119 first-hand experience) selection passes a 3-step filter, with one revise-specific addition: the existing article's already-cited bank entries count toward the density cap. R-121 is per content, not per skill invocation — replacing a stale fact with a new bank entry adds, removing one subtracts, holding one steady leaves the cap unchanged.

Step 4 (Existing Blog Parse) addition: during the BeautifulSoup parse, also extract pre-revise bank citations. Two detection paths:

• <blockquote data-bank-entry-id="exp-..." /> or <aside data-bank-entry-id="res-..." /> — explicit attribution attribute (preferred; new-blog runtime will emit this once Phase 11 Wave 2 lands).
• Text-matching fallback for older articles without data-bank-entry-id: regex against entry.claim_core + phrasings of every bank entry in project.config[content_settings. experience_database] ∪ original_research_database.

The detected entries form bank_entries_pre[]; the revise pass then runs the 3-step filter against bank_entries_pre[] ∪ candidates_new[]:

1. Topic match. entry.applicable_topics ∩ (decay_row.url_slug ∪ decay_row.matched_keywords ∪ topical_map[matching_row].cluster) ≠ ∅ → entry remains a candidate; empty intersection → entry skipped (and if it was a pre-revise entry, the removal is logged in change_summary.md as "bank entry pruned: topic no longer matches revised content").
2. Profile density cap. Apply the per-profile maximum to the union set:
   • YMYL: 2 experience + 1 research entry per content
   • b2b-saas: 1 experience + 1 research entry per content
   • e-commerce / local-service / portfolio: 1 experience + 0 research entry per content If |bank_entries_pre| already meets or exceeds the cap, no new entries are introduced during revise — the skill rotates phrasings on existing entries instead.
3. Rotation (30-day). For each NEW candidate (not pre-revise), count usage in master.xlsx[completed_work] rows where bank_entry_id == entry.id AND timestamp >= now - 30d. Skip if count >= entry.max_usage_per_month. Pre-revise entries are exempted from rotation (they are already on the page; removing them only to satisfy the rotation cap would be churn).

If a pre-revise entry fails topic match (filter 1), the revise drops it from the article; this counts as a claim_delta -= 1 for the R-88 freshness-theater check (Step 6) — a genuine content delta, not a fake bump.

R-89 canonical interplay. Bank entry attribution (the data-bank-entry-id attribute on <blockquote> / <aside>) is part of the article's content signal, not its canonical URL. Changing which entries are cited does not trigger R-89 canonical change — only URL slug changes do (R-91 redirect path).

Post-publish state mutation (Step 8 events.jsonl append):

• For each entry newly introduced in this revise, its last_used_in_content_id is set; the master.xlsx[completed_work] row records the bank_entry_id(s) added.
• For each pre-revise entry retained, no change (already counted in a prior completed_work row when the article originally shipped).
• For each pre-revise entry dropped, the change_summary.md logs the removal but does NOT touch the original completed_work row — historical attribution preserved (append-only state, R-rule events-writer discipline).

Schema enablement (v1.4, commit 8e07e1c): R-121 reads applicable_topics, phrasings, last_used_in_content_id, max_usage_per_month on each bank entry. Stage C of brand-onboarding (commit cb8df43) populates these via R-44 evidence-gated atomic write.

Runtime integration deferred to Phase 11 Wave 2. This SKILL.md section is the spec lock; scripts/production/revise_content.py does not yet exist. When Wave 2 lands the runtime, the pre-revise extraction lives in Step 4; the 3-step filter runs between Step 5 (section-targeted detect) and Step 6 (revise generate).

R-124 — YMYL Uzman İnceleme İmzası (Pre-Publish Expert-Review Sign-Off)

YMYL profillerinde (profile == "ymyl"), R-124 gereği yazar künyesi (R-28) yalnızca kayıtlı bir insan incelemesi ile geçerlidir. Revize edilmiş YMYL içeriği yayınlanmadan (Step 7 dateModified bump'tan) ÖNCE zorunlu bir inceleme-imzası adımı çalışır:

1. Operatör inceleyiciyi adlandırır. Yayın öncesi, operatör insan reviewer (inceleyenin) adını verir. Reviewer adı yoksa → DURUR #8 (RED, yayın + dateModified bump bloklu — R-124).
2. Audit kaydı (events.jsonl, append-only). Skill, inceleme kanıtını scripts/state/events_writer.append_audit(...) ile bir event_kind=audit satırına yazar:
   • audit_action="modified" (events.schema 6-değer canonical enum {created, modified, deleted, accessed, permission_changed, config_changed}).
   • audit_target="content:{project_slug}:{post-slug}" (post-slug input.url'den türetilir).
   • actor="skill:revise-content".
   • notes payload üç zorunlu alan taşır (R-124): reviewer (inceleyen adı) + review_date (ISO 8601) + content_version (R-103 revision id veya content hash).
3. Bu kayıt R-28 künyesinin arkasındaki insan inceleme kanıtıdır (Principle 1 Truth-Verifiable + EEAT Trustworthiness). İnceleme kaydı olmadan revize edilmiş YMYL içeriği yayınlanamaz; künye + belgesiz inceleme = uydurulmuş yazarlık sinyali (rater-guideline "Lowest").

READ-ONLY contract korunur: bu audit satırı _state/events.jsonl append'idir (master.xlsx WRITE değil). Non-YMYL profillerde adım atlanır.

Schema Authority Compliance

• F-2: master.xlsx[content_decay].action schema'da type/enum/ description null. Bu skill action enum'unu R-86/R-87/R-90/R-91 rules'tan rule-derived consume eder (string compare): revise / prune / redirect / delete.
• F-6: master.xlsx[content_decay].allowed_writers null → READ-ONLY consume; transaction.append/update/delete YASAK.
• F-3 (W-F1 paralel): project-config schema 1.2 + profile enum 5-value W-F1 worker tarafından uygulanıyor; bu skill profile field'ı var olduğu varsayımıyla consume eder (Principle 2 switch).
• event_type: events.jsonl event_type=content_revise (events.schema 12-value enum).

Routing (8-Step Workflow)

Step 1: master.xlsx Read + Action Verify (F-2 rule-derived)

master.xlsx[content_decay] satırı url == {input.url} filtresiyle okunur. Action string compare (schema'da enum null, R-86/R-87/R-90/ R-91 rules'tan derive):

• action == "revise" → bu skill trigger devam.
• action == "prune" → DURUR #2 (content-remediation Wave 2 domain).
• action == "redirect" → DURUR #2 (content-remediation Wave 2).
• action == "delete" → DURUR #2 (content-remediation Wave 2).

DURUR #1 trigger: existing blog yok (outputs/blog/{slug}/article. html filesystem'de bulunamıyor).

Step 2: Decay Metric Verify (R-85 Multi-Signal Threshold)

mcp__gsc__search_analytics çağrı: siteUrl={project_slug domain}, dimensions=[query, page], page filtresi {input.url}.

GSC clicks delta hesaplama: clicks_recent - clicks_previous (content_decay.clicks_delta cross-check).

R-85 multi-signal threshold:

• clicks_delta < -20% (significant drop)
• delta_pct < -15%
• trend == "down" (3-month rolling)

DURUR #3 trigger: multi-signal threshold satisfied değil → revize gereksiz, master_task sync close request emit (READ-ONLY contract — bu skill kendisi master_task'a yazmaz).

Step 3: project-config Read (Profile-Aware Switch — Principle 2)

projects/{slug}/project.config.json parse → profile field read (W-F1 schema 1.2 enum 5-value varsayımı). content_settings 14 field consume (toc_strategy, ai_training_optin, byline_policy, vs.).

Profile-aware revise switch:

• profile == "ymyl" → R-28 byline preserve + R-50 counter-argument intact.
• profile == "e-commerce" → conversational tone preserve.
• profile == "local-service" → NAP signal preserve.
• profile == "b2b-saas" → formal tone + diagram preserve.
• profile == "portfolio" → showcase entity preserve.

Step 4: Existing Blog Parse (R-89 Canonical Preserve)

outputs/blog/{slug}/article.html BeautifulSoup parse:

• <link rel="canonical"> extract → canonical_original.
• JSON-LD @graph Article.dateModified extract → dateModified_pre.
• H1/H2/H3 outline + section boundaries.
• JSON-LD @graph 5 entity (Article + Person + Organization + WebPage + BreadcrumbList) preserve list.
• content-version meta (R-103) extract → version_pre.

DURUR #6 trigger: revise içinde canonical URL change attempt → RED (R-89 immutable; URL slug change R-91 redirect path).

Step 5: R-87 Section-Targeted Detect

input.scope switch:

• scope == "section" (default) → section-targeted diff zorunlu, Step 6 devam.
• scope == "full" → DURUR #5 trigger (manuel approve gate; R-87 full-rewrite yasak default).

Section identify (target_sections[] internal state):

• Outdated section (timestamp/stat reference older than 12 ay).
• Decay-correlated section (GSC query drop matched H2 keyword).
• Broken-link section (link freshness fail).

Step 6: R-88 Freshness Theater Preempt + Revise Generate

Pre-revise snapshot:

• word_count_pre = total visible text word count.
• claim_count_pre = stat/quote/fact reference count.
• structure_hash_pre = hash(H1+H2+H3 outline tuple).

Revise generate (revision.template.md render, profile-aware tone):

• target_sections[] içinde content delta compose.
• claim/stat/source update (Principle 1 Layer 2 fact-check enforce).
• link freshness check → broken link replace (P1 Layer 3 citation).

Post-revise snapshot:

• word_count_post, claim_count_post, structure_hash_post.

R-88 freshness theater check (CRITICAL):

• word_delta = word_count_post - word_count_pre
• claim_delta = claim_count_post - claim_count_pre
• structure_changed = structure_hash_pre != structure_hash_post

DURUR #4 trigger: word_delta == 0 AND claim_delta == 0 AND NOT structure_changed → RED (sahte tarih güncelleme; dateModified bump YOK, çıktı discard).

AMBER warning: word_delta > 0 AND claim_delta == 0 AND NOT structure_changed → manuel review öner (style-only change).

Step 7: R-103 Content Version Increment + dateModified Update

Major revise detect:

• claim_delta > 5 OR
• structure_changed OR
• profile_switch detected (project-config profile değişmiş eski vs yeni snapshot).

Major revise → version increment: v1 → v2 (R-103 content- version meta increment, semver minor bump on output schema).

Minor revise (claim_delta <= 5 AND NOT structure_changed AND NOT profile_switch) → version unchanged.

dateModified update: UTC ISO 8601 now() (Article schema + visible HTML).

canonical UNCHANGED (R-89 immutable enforce).

Output write: outputs/blog/{slug}/article.html (atomic temp+ rename).

Step 8: change_summary.md + events.jsonl Append

change_summary.md format:

# Change Summary — {url}

**Revised:** 2026-XX-XXTHH:MM:SSZ
**Scope:** section
**Sections Modified:** N
**Word Delta:** +147 (1832 → 1979)
**Claim Delta:** +2 (12 → 14)
**Structure Delta:** unchanged (R-87 section-targeted)
**Version:** v1 → v2 (major revise; claim_delta=7 > 5)
**dateModified:** 2026-XX-XXTHH:MM:SSZ
**Canonical:** UNCHANGED (https://example.com/blog/post-slug)
**Profile (P2):** ymyl

## Sections Modified
1. H2 "Subheading 1" — outdated stat replaced (2024 → 2026)
2. H2 "Subheading 3" — broken link replaced
3. H2 "Subheading 5" — counter-argument added (profile=ymyl R-50)

## R-88 Freshness Theater Check
- Pre snapshot: 1832 word, 12 claim, structure_hash=abc123
- Post snapshot: 1979 word, 14 claim, structure_hash=abc123
- Result: PASS (claim_delta=2 > 0; word_delta=+147 orantılı)

## Principle 1 Truth-Verifiable Audit
- New claims: 2
- Source verified: 2/2 (R-44)
- Citations attached: 2/2 (R-105)

events.jsonl append (events.schema event_type enum):

• event_type = content_revise
• event_kind = work
• schema_version = 1.0
• actor = skill:revise-content
• target = {url}
• timestamp = UTC ISO 8601
• scope = {input.scope}
• version_increment = true|false
• word_delta, claim_delta, structure_changed (R-88 audit trail)
• canonical_preserved = true (R-89 invariant)

DURUR Conditions (8 koşul)

1. DURUR #1 — Existing Blog Yok. outputs/blog/{slug}/article. html filesystem'de bulunamıyor → R-89 canonical preserve enforce edilemez (revize için kaynak yok); kullanıcıyı new-blog skill'e yönlendir.
2. DURUR #2 — Wrong Action. content_decay.action != "revise" (prune/redirect/delete) → wrong skill; content-remediation Wave 2 domain.
3. DURUR #3 — Decay Threshold Satisfied Değil. R-85 multi-signal threshold (clicks_delta + delta_pct + trend) tüm 3 koşul sağlanmıyor → revize gereksiz, master_task close suggestion.
4. DURUR #4 — R-88 Freshness Theater Detect. word_delta == 0 AND claim_delta == 0 AND NOT structure_changed → RED, sahte tarih güncelleme; çıktı discard, dateModified bump YAPMA.
5. DURUR #5 — scope=full Overhaul. input.scope == "full" → R-87 section-targeted yasak default; manuel approve gate (skill tek başına full-rewrite yapamaz).
6. DURUR #6 — R-89 Canonical Değişim. Revise sırasında canonical URL değişim attempt → RED, immutable; URL slug change R-91 redirect path domain.
7. DURUR #7 — P1 Fact-Check Fail. Principle 1 Layer 2 post- revise fact-check fail (yeni claim'lerin kaynak verify fail) → RED, revize iptal, çıktı discard.
8. DURUR #8 — YMYL İnceleme İmzası Eksik (R-124). profile == "ymyl" ve reviewer adı verilmemiş → RED (yayın + dateModified bump bloklu). Operatör inceleyeni adlandırmalı; skill append_audit ile reviewer + review_date + content_version kaydını yazar (Principle 1 Truth-Verifiable; uydurulmuş yazarlık yasak).

READ-ONLY Contract (F-6 Enforcement)

Bu skill master.xlsx hiçbir sheet'e YAZMAZ:

• master.xlsx[content_decay] allowed_writers null (F-6) → READ- ONLY.
• master.xlsx[master_task] protected_columns 7 alan (task, category, priority, impact, duration_est_min, assignee, note) → READ-ONLY consume; revize tracking için master_task row reference okur, yazmaz. master_task sync skill (allowed_writers içinde) yazma sorumluluğunu taşır.

Sadece şu artifact'lere yazılır (outputs § + produces §):

• outputs/blog/{slug}/article.html (updated)
• outputs/blog/{slug}/change_summary.md (new)
• _state/events.jsonl (append, events.schema event_type enum)

Plugin-Agnostik Disiplin

Skill content'inde proje slug hardcode YASAK. Tüm proje referansları runtime input ({input.project_slug}, {input.url}) üzerinden çözümlenir. URL örnekleri SKILL.md'de generic placeholder (https://example.com/blog/post-slug) kullanır.

Versioning + Status

• version: "1.0" (Phase 11 Wave 1 ilk shipping).
• status: wip (Phase 11 Wave 2 stabilizasyon sonrası active promote).
• Output schema_version: 1.0 (events.jsonl payload + change_summary format kontratı).