Part 4 of 5. ← Part 1: The Why · ← Part 2: The Architecture · ← Part 3: AI Curation Workflows · → Part 5: The Publishing Pipeline
The first three posts built the system: the reasoning in part 1, the Hugo structure in part 2, and the capture plus curation workflows in part 3. This part is about what keeps it alive once the novelty wears off.
A second mind does not fail because capture is hard. It fails because standards drift, links rot, and publishing quality drops when you are tired. If you want this to stay useful, maintenance has to be designed in.
Why ongoing maintenance matters more than capture
Capture gives you volume. Maintenance gives you trust.
Without regular checks, small problems stack up quietly. A post goes live without a clear description. A heading jumps from H2 to H4. A canonical URL points to the wrong page after a rename. None of those break the site on day one, but together they make content harder to find, harder to read, and harder to reuse.
The cost shows up later. You lose confidence in search results, visitors bounce because pages are unclear, and writing new posts gets slower because you stop trusting your own archive.
If the system is meant to reduce cognitive load, maintenance is not optional admin. It is the mechanism that keeps the system honest.
Use specialised review agents for repeatable quality
General prompts are fine for ideas. Quality control needs specialised checks. In this repo, that means using distinct review lenses for content, Hugo implementation, and design plus accessibility.
Content voice review agent
Use this before publishing any substantial post. It catches the drift that appears when you write quickly: jargon that is not explained, abstract claims with no action, and fluffy wording that sounds polished but says very little.
Use it to check:
- Does every technical term have plain-language context or a link?
- Can a reader act on each section in under 10 minutes?
- Are you writing directly, or hiding uncertainty behind vague language?
Concrete example: if a paragraph says “optimise your workflow for better retrieval”, rewrite it to “add three internal links from your new post to older related posts”. That gives a reader a task, not a slogan.
Hugo practices review agent
Use this when editing templates, front matter patterns, archetypes, or config. It keeps implementation details aligned with how Hugo actually behaves in this project.
Use it to check:
- Front matter remains consistent across content types
- Template logic uses the expected Hugo patterns (
with, trimmed delimiters, scoped variables) - Public and private environments still enforce the draft boundary
Concrete example: when adding a new content section, review agent feedback should confirm that buildDrafts behaviour still matches the private mode design from part 2.
Design and accessibility review agent
Use this when touching templates or styles. A site can be technically valid and still hard to use.
Use it to check:
- Heading order is logical and scannable
- Colour contrast meets WCAG expectations in real states, including focus
- Interactive elements remain keyboard accessible
Concrete example: if a link style looks fine on hover but loses visible focus outline, treat that as a release blocker, not a cosmetic tweak.
SEO checks to run regularly (and quickly)
SEO maintenance is mostly consistency work. You do not need a massive dashboard. You need a short list that catches common regressions.
Run this on every new post, then as part of a weekly pass:
- Metadata: Title is specific, description is concrete, and both match what the page actually delivers.
- Canonical URL: Each page points at its own canonical, especially after slug edits or content moves.
- Heading structure: One H1 from front matter title, body starts at H2, no skipped levels.
- Internal links: New posts link back to relevant older posts and series entries.
- Performance basics: Featured image is compressed, no huge assets slipped in, and page weight stays reasonable.
Use this quick table during reviews:
| Check | What good looks like | Fix when broken |
|---|---|---|
| Metadata | Title and description match intent and user query | Rewrite for specificity, cut vague phrasing |
| Canonical | Canonical points to final URL | Update front matter or template output |
| Headings | Clear H2 and H3 flow, no jumps | Reorder headings, split overloaded sections |
| Internal links | At least 2 useful links to related pages | Add links to series parts and prior posts |
| Performance | Images and scripts stay lean | Replace oversized media, defer non-critical assets |
This is where agents help. They can flag omissions quickly, but you decide what counts as a meaningful fix.
Automate the weekly audit in GitHub
Manual rituals are useful, but automation is what makes them reliable. I now run the review as a scheduled GitHub Action so it happens even when the week gets messy.
The workflow runs every Monday and does three things:
- Runs the three specialised agents against the right parts of the site.
- Creates one parent “weekly audit” issue with the full findings.
- Splits every blocker into its own actionable issue.
The current schedule is deliberate:
- 08:00 UTC Monday: run the audit and open findings issues.
- 12:00 UTC Monday: run auto-promote.
That gap gives you a morning window to merge fixes, so changes that meet your promotion criteria can be included in the same day’s promotion run.
What this automation reviews
- Content Voice Reviewer on published blog posts (
content/blog/**/index.md) - Hugo Practices Reviewer on templates, config, archetypes, and SCSS (
layouts/**,config/**,archetypes/**,assets/**) - Design Reviewer on templates and SCSS (
layouts/**/*.html,assets/**/*.scss)
How findings become actions
The workflow writes a full markdown report and creates issues automatically:
- One
auditissue for weekly visibility - One
audit+blockerissue per blocker finding
Each blocker issue includes:
- the exact problematic text or code
- the affected file path
- a concrete suggested fix
- a note to assign to
@copilotfor implementation
That means you move from “there is a quality problem” to “this specific fix is queued” without copy-pasting from chat into tickets.
Why this works better than an ad-hoc checklist
You still keep human judgement at the end, but the boring coordination is gone.
- Reviews run on time every week
- Findings are structured the same way every time
- Blockers are hard to ignore because they are tracked as issues
- Promotion timing can include same-day fixes
The practical outcome is simple: less drift, faster clean-up, and fewer surprises when you publish.
Stop agent overreach and keep human judgement in control
Agents are great at consistency checks. They are not accountable for your voice, your risk tolerance, or your publishing standards.
Set clear boundaries:
- Agents can suggest edits, never silently publish content
- Agents can flag sensitive text, but humans make the final call
- Agents can rank issues, but humans choose tradeoffs
A useful rule is “no irreversible action without explicit confirmation”. That covers publication, deletion, major rewrites, and taxonomy changes.
Another useful rule is “ask for reasons, not just results”. If an agent says a section is weak, it should explain why in plain language and point to the exact text.
The goal is not to replace editorial judgement. The goal is to spend your judgement where it matters, instead of wasting it on repetitive checks.
Conclusion
Part 1 to part 3 built capture and curation. Part 4 keeps the whole system healthy. The difference is discipline, not tooling.
A lightweight weekly automated audit, backed by specialised review agents and clear human gates, stops quality decay before it becomes expensive.
Next steps
- Add the weekly audit workflow and run it once with
workflow_dispatchto validate output quality. - Triage any
blockerissues first, then assign them to@copilotwhere automation is safe. - Keep Monday morning free for fast fixes before the Monday mid-day auto-promote run.