Technical SEO Agent

5 min read

🔧 Technical SEO Agent

BaC Principle

“Technical SEO is the plumbing. No amount of content quality fixes a crawl budget problem or a broken canonical chain. Automate the audit; codify the fix specs.” — Business as Code Manifesto

Stage: S6 — Technical SEO Type: AUTO (~75% automated — fixes requiring code deploy escalate to dev) Trigger: After S5 produces aeo_ready_content; also runs monthly on full site Output feeds: 09-Human-Review-Gates (Content Review), dev team for code fixes

See Map of Content for full vault navigation.

🎯 Objective

Implement all resolvable technical SEO fixes from the S1 audit, inject validated schema markup from S5, and generate precise implementation specs for issues that require developer action. Ensure the site is fully crawlable, indexable, and technically capable of earning the rankings and citations that content optimization targets.

🛠️ Tools & Integrations

tools:
  - name: Screaming Frog SEO Spider
    used_for: Re-crawl after content updates; verify fixes applied correctly
    api: CLI / scheduled crawl export
 
  - name: PageSpeed Insights API
    used_for: Core Web Vitals monitoring; identify CWV regressions
    api: REST API
 
  - name: Google Search Console API
    used_for: Coverage report (indexing errors, excluded pages); submit sitemap
    api: REST API
 
  - name: Claude API
    used_for: >
      Generate implementation specs for technical fixes (with code snippets),
      write redirect mapping logic, generate updated robots.txt and sitemap XML
    api: Messages API
 
  - name: Schema.org validator
    used_for: Final validation of all schema markup before publish
    api: REST API

⚡ Execution Steps

flowchart TD
    A["Receive aeo_ready_content<br/>+ technical_issues from S1 audit"]
    B["Prioritize issues<br/>Critical → High → Medium → Low"]
    C{"Issue type?"}
    D["AUTO-fixable:<br/>Meta tags, redirects, canonical,<br/>sitemap, robots.txt, schema inject"]
    E["Needs dev deploy:<br/>Page speed, JS rendering,<br/>hreflang, structural changes"]
    F["Apply AUTO fixes<br/>Generate updated files/content"]
    G["Generate fix specs<br/>For dev: priority + effort + code snippet"]
    H["Inject schema markup<br/>From AEO Structuring Agent S5"]
    I["Submit updated sitemap<br/>to Google Search Console"]
    J["Re-crawl sample<br/>Verify critical fixes applied"]
    K["Output: technical_fix_specs<br/>+ publish-ready content"]

    A --> B --> C
    C -- Auto-fixable --> D --> F --> H --> I --> J --> K
    C -- Needs dev --> E --> G --> K

🛠️ Issue Categories & Automation Level

issue_categories:
  auto_fixable:
    - type: missing_meta_description
      action: Generate and inject from content brief
      automation: 100%
 
    - type: duplicate_meta_description
      action: Rewrite unique meta for each page
      automation: 100%
 
    - type: missing_canonical
      action: Inject self-referencing canonical
      automation: 100%
 
    - type: broken_internal_link
      action: Fix URL path or add 301 redirect
      automation: 90%   # 10% require human URL decision
 
    - type: redirect_chain
      action: Collapse to single redirect
      automation: 85%
 
    - type: missing_xml_sitemap_entry
      action: Regenerate sitemap with missing URLs
      automation: 100%
 
    - type: schema_missing_or_invalid
      action: Inject validated JSON-LD from S5 output
      automation: 100%
 
    - type: missing_alt_text
      action: Generate descriptive alt text via Claude API
      automation: 90%
 
    - type: robots_txt_blocking_key_pages
      action: Generate updated robots.txt with fix
      automation: 80%   # human must approve before deploy
 
  requires_dev:
    - type: core_web_vitals_lcp_fail
      action: Generate optimization spec (image lazy load, CDN, render-blocking JS)
      effort_estimate: "medium"
      escalate_to: dev_team
 
    - type: core_web_vitals_cls_fail
      action: Generate fix spec (image dimensions, layout shift sources)
      effort_estimate: "low–medium"
      escalate_to: dev_team
 
    - type: javascript_rendering_issue
      action: Generate spec for SSR or pre-rendering implementation
      effort_estimate: "high"
      escalate_to: dev_team
 
    - type: hreflang_errors
      action: Generate correct hreflang attribute map
      effort_estimate: "low"
      escalate_to: dev_team
 
    - type: page_depth_greater_than_3
      action: Generate internal linking restructure plan
      effort_estimate: "medium"
      escalate_to: dev_team

📤 Output Schema

{
  "technical_fix_run_id": "techseo_2026-04-02",
  "processed_at": "2026-04-02T22:00:00Z",
  "issues_addressed": 23,
  "auto_fixed": 18,
  "escalated_to_dev": 5,
  "auto_fixes": [
    {
      "issue_type": "missing_meta_description",
      "pages_fixed": 12,
      "fix_applied": "Meta descriptions generated and injected",
      "status": "ready_to_publish"
    },
    {
      "issue_type": "schema_missing_or_invalid",
      "pages_fixed": 8,
      "fix_applied": "FAQPage + Article JSON-LD injected",
      "schema_validated": true,
      "status": "ready_to_publish"
    }
  ],
  "dev_specs": [
    {
      "issue_id": "issue_015",
      "type": "core_web_vitals_lcp_fail",
      "priority": "high",
      "affected_urls": ["https://businessascode.co/", "https://businessascode.co/use-cases/"],
      "lcp_current_ms": 4200,
      "lcp_target_ms": 2500,
      "effort_estimate": "medium",
      "fix_spec": "Implement lazy loading for hero images. Add width/height attributes to prevent CLS. Consider WebP format conversion for all images > 100KB.",
      "code_snippet": "<img src='hero.webp' alt='...' width='1200' height='600' loading='lazy' />"
    }
  ],
  "sitemap_updated": true,
  "sitemap_submitted_to_gsc": true,
  "re_crawl_issues_remaining": 2
}

📊 KPIs

MetricTargetAlert Condition
Critical issues resolved100%Any unresolved → block publish
High issues resolved / specced100%Any unaddressed → flag
Core Web Vitals pass rate≥ 75% of pages< 60% → escalate CWV sprint to dev
Schema validation pass rate100%Any fail → fix before publish
Indexed pages (GSC)Growing week-over-weekStagnation > 2 weeks → investigate
Re-crawl broken links0> 0 → re-run auto-fix

⚠️ Error Handling

error_rules:
  - condition: Auto-fix breaks page layout or content
    action: Revert change; flag page for manual fix
    fallback: Skip page in this cycle; add to next sprint
 
  - condition: Sitemap submission to GSC fails (auth error)
    action: Retry with refreshed auth token
    fallback: Flag for manual sitemap submission by CMO
 
  - condition: Schema injection creates invalid HTML structure
    action: Remove injected schema; re-generate with strict HTML validator
    fallback: Output schema as separate JSON-LD file (not inline)
 
  - condition: Re-crawl finds new broken links introduced by content updates
    action: Auto-fix redirect or URL; add to auto_fixes log
    fallback: Flag as "introduced_by_content_batch" for immediate attention

📎 Related Files

Graph View

Backlinks