From a2af04f2c4bc1273b9753d0cbe7a9860b0ad23eb Mon Sep 17 00:00:00 2001 From: peptiderepo <273788462+peptiderepo@users.noreply.github.com> Date: Fri, 19 Jun 2026 16:25:53 +0700 Subject: [PATCH] docs: add app-local ADR log + ADR-0001 editorial illustration image style (#169) Adds docs/adr/ scaffold (README index) and ADR-0001 documenting the v0.16.0 pivot to text-free editorial illustration with caption-as-HTML. Agent-Session: adr-scaffold-20260617 --- ARCHITECTURE.md | 2 + CHANGELOG.md | 1 + ...0001-editorial-illustration-image-style.md | 163 ++++++++++++++++++ docs/adr/README.md | 26 +++ 4 files changed, 192 insertions(+) create mode 100644 docs/adr/0001-editorial-illustration-image-style.md create mode 100644 docs/adr/README.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index aba3fe4..d6208a1 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -2,6 +2,8 @@ > **Cross-app context:** decisions that affect multiple plugins (Cloudflare AI Gateway routing, OpenRouter account sharing, the interface pattern, image-generation stack, social distributor choice) are recorded in `Peptide Repo CTO/docs/engineering/decisions/`. The incident runbook for cross-app failure modes is at `Peptide Repo CTO/docs/engineering/INCIDENT-RUNBOOK.md`. Engineer PRAutoBlogger should read both before making decisions that cross plugin boundaries. +> **App-local decisions:** choices that affect only this plugin are recorded in [`docs/adr/`](docs/adr/README.md) — a per-repo numbered log (0001, 0002, …). Read `docs/adr/README.md` for the index. The routing rule and required template live centrally in `Peptide Repo CTO/docs/engineering/ADR-PROCESS.md`. + PRAutoBlogger is a WordPress plugin that monitors social media (starting with Reddit) for recurring questions, complaints, and comparisons in a configured niche, uses LLM agents (via OpenRouter) to generate high-quality blog articles from those insights, runs them through a chief editor agent for quality review, and auto-publishes them on a configurable daily schedule. All collected data and generation metrics are stored for a self-improvement feedback loop. --- diff --git a/CHANGELOG.md b/CHANGELOG.md index e774d54..3416c14 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ and this project uses [Semantic Versioning](https://semver.org/). ## [Unreleased - Internal] ### Internal +- ADR log scaffolded: `docs/adr/` created as the app-local decision log for this plugin; `docs/adr/README.md` is the index; ADR-0001 documents the v0.16.0 editorial illustration image-style pivot. `ARCHITECTURE.md` updated to point to the folder. No runtime changes; docs-only. - CI constants guard (`scripts/check-constants.php`): new required CI step (`Check PRAUTOBLOGGER_* constants`) fails the build when any `PRAUTOBLOGGER_*` constant referenced in shipped plugin PHP is neither defined in `prautoblogger.php` nor `defined()`-guarded at the reference site. Prevents a recurrence of the v0.19.0 admin-500 regression class. ## [0.22.0] - 2026-06-16 diff --git a/docs/adr/0001-editorial-illustration-image-style.md b/docs/adr/0001-editorial-illustration-image-style.md new file mode 100644 index 0000000..aebe0f9 --- /dev/null +++ b/docs/adr/0001-editorial-illustration-image-style.md @@ -0,0 +1,163 @@ +# ADR-0001: Editorial illustration image style — pivot from comic to text-free illustration with caption-as-HTML + +- **Status:** Accepted +- **Date:** 2026-05-29 +- **Deciders:** CTO, Engineer PRAutoBlogger +- **Supersedes:** — +- **Superseded by:** — +- **Related:** ARCHITECTURE.md §#20; CHANGELOG.md [0.16.0]; PR #146 (d00e746); + `docs/proposals/2026-05-29-image-pipeline-in-plugin-brief.md`; + ARCHITECTURE.md §#21 (v0.17.0 deterministic composer, the follow-on commit) + +--- + +## Context + +PRAutoBlogger generates two AI images (A/B pair) for each article and publishes +them as featured images. From the initial comic-strip launch (commit b17ed47, +`feat: switch to single-panel newspaper comic style for article images`) through +v0.15.x, the image style was a **single-panel newspaper comic** — the rewriter +LLM was asked to produce a comic gag or visual pun, and the result was appended +to a style suffix and sent to the diffusion model. + +By April 2026 two problems had accumulated: + +1. **Text legibility.** Small diffusion models (FLUX.1 schnell is the default + since v0.9.0 at ~$0.0006/image) cannot reliably render readable text inside + an image. Comic panels depend on legible speech bubbles or captions burned + into the image; both were routinely garbled (confirmed in the 2026-04-21 A/B + finding documented in ARCHITECTURE.md §#21). + +2. **Caption path already existed.** A separate HTML caption below the image had + been extracted as early as commit 214f57b (`Separate comic captions from + generated images`, 2026-04-18). The scene/caption split in + `Image_Scene_Parser` was already live, meaning there was an established path + for readable text that did not depend on the diffusion model rendering it. + +Together these created pressure to stop asking the diffusion model to render +text at all, and instead shift all readable copy to the HTML caption path that +was already in place. + +## Decision drivers + +1. **Image quality on default model.** FLUX.1 schnell (the default since v0.9.0) + produces garbled text in generated images. A style that depends on readable + in-image text degrades silently on the model we actually ship. +2. **Editorial trust signal.** Peptide Repo's editorial direction is + science-informational; comic gags undercut the authority the site needs for + health-adjacent content. +3. **Reuse the existing caption path.** The scene/caption split and HTML caption + path were already live; the change is a prompt rewrite + template substitution + with no new infrastructure. +4. **Admin configurability.** The style suffix was a single string appended to + every prompt; a template with a named substitution token (`{{ topic_summary + }}`) is more maintainable and admin-overridable without a code deploy. +5. **Cost and provider neutrality.** The change is prompt-only; provider, model, + and pricing are unchanged. + +## Options considered + +### Option A — Keep the comic style, fix text rendering per-model + +Ask the rewriter LLM to omit text from comic panels (no speech bubbles, no +caption burns), and describe a visual scene instead. Keep the style suffix +pattern. + +**Pros:** +- Minimal code change — just a prompt edit. +- Comic aesthetic is recognisable and differentiating. + +**Cons:** +- Does not solve the underlying mismatch: the style suffix is a static string + that gives no per-article context to the diffusion model. The rewriter scene + still has no slot to insert topic-specific imagery. +- Comic gags require the LLM to invent a joke per peptide, which is inconsistent + in tone. +- Comic aesthetic conflicts with the editorial trust direction for health content. + +### Option B — Pivot to text-free editorial scientific illustration + template substitution (chosen) + +Change the rewriter system prompt so the LLM emits a concise 1-2 sentence +topic/mechanism summary as the SCENE — one concrete centered focal subject, no +text, no people-as-gag, no logos. Replace the style suffix with an editable +template (`prautoblogger_image_style_template`) that contains a single +`{{ topic_summary }}` token filled per-article by +`PRAutoBlogger_Image_Template_Filler`. The CAPTION line from the scene/caption +split continues to flow to the HTML-caption-below-image path unchanged. + +**Pros:** +- Diffusion model is never asked to render text; garbled-text failures are + eliminated. +- The editorial scientific illustration style is consistent with the site's + authority positioning. +- Template substitution gives admins a single editable field to control the + entire visual style without touching the per-article rewriter logic. +- Degradation is explicit: missing token → append + warning; empty summary → + style-only prompt; a blank prompt is never sent to the provider. +- Provider, model, and cost are unchanged. + +**Cons:** +- Breaks the comic gag aesthetic for any site running PRAutoBlogger in a + context where that was intentional (low risk for this deployment). +- The old `prautoblogger_image_style_suffix` option must be migrated + (handled via one-time migration `prautoblogger_migrated_style_template_v0160` + and mirroring to `_deprecated` for one cycle). + +### Option C — Generate text overlays in PHP (deterministic composer only) + +Skip the style change; solve legibility by compositing text onto images in PHP +after the diffusion model runs. + +**Pros:** +- Diffusion model input is unchanged (comic style preserved). +- Composited text is always readable regardless of model. + +**Cons:** +- Compositing a comic-style gag is much harder than compositing a caption band + (arbitrary layout vs. a fixed panel at the bottom). +- Does not address the editorial direction mismatch. +- The deterministic PHP composer (ARCHITECTURE.md §#21) was already planned as + a follow-on commit specifically for OG/social variants — pursuing it as the + sole fix conflates two separate problems. + +## Decision + +**Option B** — pivot to text-free editorial scientific illustration with +caption-as-HTML and template substitution. + +This was shipped as v0.16.0 (2026-05-29, PR #146, commit d00e746). The changes +are entirely in the prompt layer: + +- `Image_Prompt_Builder::REWRITER_SYSTEM_PROMPT` now asks for a concise + topic/mechanism SCENE and keeps the CAPTION line for the HTML path. +- `PRAutoBlogger_Image_Template_Filler::fill()` replaces the old + `trim($scene . ' ' . $style_suffix)` concat at all three entry points + (`build_article_prompt`, `build_source_prompt`, `build_fallback_prompt`). +- New admin setting `prautoblogger_image_style_template` with + single-token validation replaces the Style Suffix field. +- One-time migration preserves the old suffix value for one cycle. + +The deterministic PHP composer for OG/social branding (ARCHITECTURE.md §#21) +was deliberately deferred to a follow-on commit (v0.17.0, #152) so that the +prompt-only change could ship and be verified first. + +## Consequences + +**Accepted benefits:** +- Garbled-text image failures are eliminated on the default FLUX.1 schnell model. +- The editorial scientific illustration style is consistent with the site's + health-content positioning and sustainable across future model changes. +- The template + token pattern makes style updates admin-configurable without + code changes. + +**Accepted costs:** +- The comic aesthetic is gone and cannot be restored by toggling a setting; + switching back requires a prompt and template change. +- The `prautoblogger_image_style_suffix` option is deprecated; the migration + runs once on upgrade and the old option is not deleted until a future cycle. + +**Follow-up created:** +- ARCHITECTURE.md §#21 (v0.17.0): deterministic PHP image composer to composite + branded OG and square card variants — necessary because the social/OG image + travels without the HTML caption and therefore needs text burned in by PHP, + not by the diffusion model. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..39b5827 --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,26 @@ +# PRAutoBlogger — App-Local ADR Log + +This folder is the per-repo decision log for the **PRAutoBlogger** plugin. +It records architectural choices that affect this codebase alone. + +**Cross-cutting decisions** (spanning multiple plugins, shared infra, or +CI/deploy standards) live centrally in +`Peptide Repo CTO/docs/engineering/decisions/`. + +For the routing rule, required sections, and status lifecycle, read the +canonical process document: +`Peptide Repo CTO/docs/engineering/ADR-PROCESS.md` + +The canonical template for new ADRs is: +`Peptide Repo CTO/docs/engineering/adr-template.md` + +## Numbering + +ADRs in this folder use a per-repo zero-padded sequence starting at `0001`. +A new ADR always gets the next unused number; numbers are never reused. + +## Index + +| Number | Title | Status | Date | +|--------|-------|--------|------| +| [0001](0001-editorial-illustration-image-style.md) | Editorial illustration image style — pivot from comic to text-free illustration with caption-as-HTML | Accepted | 2026-05-29 |