Designing Repair Mode for LLMWikis.org

Full report

On this page

Executive Summary

LLMWikis.org already treats repair as a first-class use case. The Setup Wizard’s stated purpose includes repairing an existing wiki by defining scope, taxonomy, canonical URLs, metadata, source policy, review gates, redirects, and “safe staged migration work,” and it explicitly supports both “Improve or repair an existing wiki” and “Advanced multisite workspace” modes. At the same time, the wizard’s current public boundary is intentionally conservative: it is a browser-only planner that produces a copyable Markdown packet and structured JSON, while explicitly not supporting automatic repository writes or automatic publication. That combination strongly suggests that a production “repair mode” should be designed in layers: first as a standards-aware assessor and staging system, then as an approval-gated remediation system with optional platform-specific write adapters.

The quality bar should be defined by LLMWikis’ own standards rather than by generic SEO or generic wiki hygiene. LLMWikis describes a high-quality wiki as one with exportable files and history, explicit metadata, canonical URLs, typed navigation, trust labels, source policy, human review for AI-generated edits, and clear security/privacy boundaries. Its completion test is especially useful: a new human or AI agent should be able to tell what the wiki covers, where to start, what is authoritative, what is sensitive, who owns each core page, what may be edited, what requires human approval, and what remains unknown.

The recommended architecture is a five-part pipeline: platform adapters, normalization, standards/rule evaluation, staged remediation generation, and approval-governed publication. That model aligns with LLMWikis’ repair guide, which frames repair as an information architecture migration rather than a cleanup pass, and with its two-step operations guidance, which separates analysis from writes so risky decisions can be reviewed before the wiki changes. For multi-site organizations, the same architecture should scale by adding a workspace root, site registry, cross-site canonical registry, and per-site policy overlays rather than by building a different product.

A pragmatic v1 should therefore produce four primary outputs: a scorecard against LLMWikis standards, a migration map of old URLs to canonical targets, a machine-readable remediation model, and a human-readable restructure packet for review. A later phase can add controlled writers for Git-based wikis, MediaWiki, DokuWiki, and Confluence, but destructive publication should remain explicitly review-gated.

Standards Baseline and Success Metrics

Repair mode should measure success against the standards that LLMWikis repeatedly emphasizes: one durable canonical URL per important concept; page-first structure; explicit index and log; typed related links and breadcrumbs; required metadata; trust labels and freshness rules; source-linked publication; and security/privacy controls that keep sensitive material out of public discovery and portable exports. Public discovery should be generated from canonical public pages only, using sitemap.xml and llms.txt, while graph views, JSON, APIs, and other derived surfaces remain secondary to reviewed canonical pages.

The following targets translate that guidance into an operational scorecard. The percentages are recommended implementation thresholds for repair mode, not official LLMWikis conformance values.

Public pages should also be machine-readable outside the wiki platform itself. The Sitemaps protocol exists to list site URLs and optional metadata for crawlers, Google supports sitemap formats defined by that protocol, and llms.txt is an emerging root-level proposal intended to help LLMs use a website at inference time. For public HTML pages, repair mode should also validate canonical link behavior and structured data. Schema.org is a suitable primary vocabulary here: WebPage can describe pages generally, TechArticle or Article can describe page-type-specific content, and BreadcrumbList can describe breadcrumb trails.

Inputs and Platform Adapters

Repair mode needs more than a starting URL. LLMWikis’ repair sequence explicitly begins by listing pages, routes, files, indexes, public URLs, sitemap entries, llms.txt entries, and internal links; the wizard’s required outputs similarly call for the root URL or repository path, raw source path, compiled wiki path, index/log paths, root index topology, and owner/review/trust/sensitivity/citation/lint policy. In other words, repair mode should treat discovery, content, and governance inputs as equally important.

The table below summarizes the major platform differences that a repair-mode adapter layer must absorb. These assumptions come from official platform documentation for MediaWiki, DokuWiki, Confluence, GitHub, and GitLab. MediaWiki exposes Action and REST APIs along with XML export and backup guidance; DokuWiki exposes XML-RPC and JSON-RPC, ACLs, XML sitemap generation, and file-copy backup; Confluence Cloud exposes REST resources plus export and permissions workflows; GitHub wikis are Git repositories with repository-based permissions; and GitLab offers both project and group wikis, with Git-backed storage and REST APIs.

A practical normalization layer should hide those differences behind a common internal model such as PageRecord, with fields for page locator, canonical candidates, source form, rendered form, outgoing and incoming links, permissions, revision history, media references, existing metadata, and discovery-surface membership. Where platforms cannot safely host full frontmatter in the page body, repair mode should support metadata sidecars keyed by canonical URL or stable page ID. That recommendation follows from the LLMWikis metadata standard combined with the reality that the supported wiki platforms expose different native storage models and markup conventions.

Detection and Remediation Engine

The detection engine should combine deterministic validation with bounded LLM-assisted analysis. Deterministic checks should cover inventory completeness, canonical collisions, breadcrumb coverage, related-link coverage, required metadata presence, stale review dates, invalid trust or status values, redirect correctness, broken internal links, sitemap/llms mismatches, and restricted-content leakage into public discovery. LLM-assisted analysis should be reserved for tasks that are difficult to encode but still bounded by evidence: page-intent classification, duplicate concept clustering, contradiction extraction, mega-page split suggestions, and canonical-winner recommendations. That division follows LLMWikis’ own repair sequence and two-step pipeline: inventory first, classify, find failure modes, choose canonical winners by intent, then stage updates for review before anything is written.

The workflow below extends LLMWikis’ analyze-stage-review-write pattern into an end-to-end repair pipeline while preserving the wizard’s current non-automatic-publication boundary.

flowchart TD
    A[Select Repair Mode in Wizard] --> B[Connect sites, exports, and credentials]
    B --> C[Inventory and normalize pages, files, links, metadata, permissions]
    C --> D[Run deterministic validators]
    C --> E[Run LLM-assisted classifiers]
    D --> F[Combine findings into scorecard and migration map]
    E --> F
    F --> G{Remediation class}
    G -->|Safe and reversible| H[Generate auto-fix patch bundle]
    G -->|Semantically risky| I[Generate manual review queue]
    H --> J[Stage in PR, MR, shadow wiki, or staging space]
    I --> J
    J --> K[Human approval gates]
    K -->|Approved| L[Platform-specific publish]
    K -->|Rejected or deferred| M[Revise mapping, ownership, or rules]
    L --> N[Re-run lint, redirect, sitemap, llms, and monitoring checks]

The next table shows concrete examples of remediation rules. The rules are derived from LLMWikis’ repair, metadata, navigation, trust, source-policy, and security guidance, while the automation feasibility, risk, and timing columns are implementation estimates for a repair-mode product.

A sound operating policy is to auto-apply only fixes that are deterministic, reversible, and semantics-preserving. Anything that changes authority, meaning, privacy classification, or inter-page trust should move to assisted or manual review. That is especially important because LLMWikis explicitly says agents should stop on missing permission, secrets, private data, unsupported claims, destructive moves, or ambiguous authority.

Workflow, Wizard UX, and API Design

In product terms, repair mode should look like a natural extension of the current Setup Wizard rather than a separate control panel. The wizard already supports existing-wiki repair, multisite setup questions, root index topology, trust labels, review gates, linting, and support escalation, and it already produces both human-readable Markdown and structured JSON. The best UX move is therefore to keep the wizard as the intake and planning surface, then add deeper analysis and staging screens after a user selects an existing wiki or advanced multisite workspace.

A strong wizard flow would have five screens. The connection screen gathers target URLs, platform hints, discovery files, and credentials. The inventory screen previews what was found, what was authenticated, and where coverage gaps remain. The standards scorecard screen reports findings by structural, content, metadata, governance, and safety class. The remediation screen lets admins filter findings into safe auto-fixes, assisted fixes, and manual-only items, with patch previews and migration maps. The final staging screen exports the restructure packet, machine-readable model, patch bundle, and updated discovery artifacts, or sends them into a PR/MR, staging wiki, or staging space. That mirrors the wizard’s current “copy packet and JSON model into a staged review issue or repository note before writing” posture.

The admin dashboard should then become the operational surface. It should expose site and sub-site filters, rule severity, approval state, owner queues, redirect map coverage, discovery-surface health, stale-review trends, and remediation velocity. It should also support a “canonical graph” visualization, but that graph must remain derived from page-level truth rather than treated as a competing source of truth. LLMWikis is explicit that canonical pages are primary, while graph views, maps, JSON, APIs, and retrieval surfaces are secondary.

The API contract for the dashboard and any CI/CD integration should be OpenAPI-based. That is a good fit because the OpenAPI Specification is expressly designed to let both humans and computers discover and understand HTTP services, and the repair-mode outputs map cleanly to structured request/response models. The sample below shows a compact but realistic schema shape.

openapi: 3.1.0
info:
  title: LLMWikis Repair API
  version: 1.0.0
paths:
  /repair-jobs:
    post:
      summary: Analyze one or more wikis and generate a remediation packet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RepairJobRequest'
      responses:
        '202':
          description: Repair job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepairJobAccepted'
  /repair-jobs/{jobId}:
    get:
      summary: Get repair job status and results
      parameters:
        - in: path
          name: jobId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Repair job result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepairJobResult'
components:
  schemas:
    RepairJobRequest:
      type: object
      required: [mode, targets]
      properties:
        mode:
          type: string
          enum: [single-site, multi-site]
        targets:
          type: array
          items:
            $ref: '#/components/schemas/WikiTarget'
        policy:
          $ref: '#/components/schemas/RepairPolicy'
    WikiTarget:
      type: object
      required: [rootUrl]
      properties:
        rootUrl:
          type: string
          format: uri
        platform:
          type: string
          enum: [auto, mediawiki, dokuwiki, confluence, github-wiki, gitlab-wiki]
        sitemapUrl:
          type: string
          format: uri
        llmsUrl:
          type: string
          format: uri
        exportBundleRef:
          type: string
        authRef:
          type: string
        scopeKey:
          type: string
          description: Space key, namespace, repo, group, or site alias
    RepairPolicy:
      type: object
      properties:
        allowAutoFix:
          type: boolean
        publishMode:
          type: string
          enum: [report-only, stage-only, approval-gated]
        sensitivityDefault:
          type: string
        requiredApprovals:
          type: array
          items:
            type: string
    RepairJobAccepted:
      type: object
      required: [jobId, status]
      properties:
        jobId:
          type: string
        status:
          type: string
          enum: [queued, running, completed, failed]
    RepairJobResult:
      type: object
      required: [jobId, status, scorecard, remediationActions, artifacts]
      properties:
        jobId:
          type: string
        status:
          type: string
          enum: [completed, failed]
        schemaVersion:
          type: string
        scorecard:
          $ref: '#/components/schemas/Scorecard'
        remediationActions:
          type: array
          items:
            $ref: '#/components/schemas/RemediationAction'
        migrationMap:
          type: array
          items:
            $ref: '#/components/schemas/MigrationItem'
        artifacts:
          type: object
          properties:
            markdownPacketRef:
              type: string
            jsonModelRef:
              type: string
            patchBundleRef:
              type: string
            sitemapRef:
              type: string
            llmsRef:
              type: string
    Scorecard:
      type: object
      properties:
        inventoryCoverage:
          type: number
        metadataRequiredComplete:
          type: number
        orphanPublicPages:
          type: integer
        duplicateCanonicalCandidates:
          type: integer
        ownerlessAuthorityPages:
          type: integer
        restrictedInPublicDiscovery:
          type: integer
    RemediationAction:
      type: object
      required: [actionId, ruleId, decision, targetRef, risk, automation]
      properties:
        actionId:
          type: string
        ruleId:
          type: string
        decision:
          type: string
          enum: [keep, move, merge, split, redirect, archive-noindex, retire, needs-human-decision]
        targetRef:
          type: string
        risk:
          type: string
          enum: [low, medium, high, very-high]
        automation:
          type: string
          enum: [safe-auto, assisted, manual]
        estimatedMinutes:
          type: integer
        requiredApprovals:
          type: array
          items:
            type: string
    MigrationItem:
      type: object
      required: [oldUrl, newUrl, action, redirectType, canonicalTarget, reason]
      properties:
        oldUrl:
          type: string
        newUrl:
          type: string
        action:
          type: string
        redirectType:
          type: string
        canonicalTarget:
          type: string
        reason:
          type: string

A matching result document should include a scorecard, a finding summary, the remediation queue, and a migration map, plus references to human-readable and machine-readable artifacts. That output shape matches the wizard’s current structured-model approach, the repair guide’s decision model, and its prescribed migration-map fields such as old_url, new_url, action, redirect type, canonical target, and reason.

Single-site and org-level repair should share one mental model. In a single-site wiki, the root index can enumerate all durable pages. In a multisite workspace, LLMWikis says the root index should route to sub-wiki directories and global-only files such as organization policy and governance. Platform-specific mappings follow from that: Confluence spaces are natural sub-wikis within a site; GitLab group wikis are natural org-level docs containers; MediaWiki and DokuWiki often segment content with namespaces; and for GitHub, organization-level repair is best understood as fleet analysis across multiple repository wikis because each repository gets its own wiki.

CI/CD should mirror that same split between safe structure and meaningful governance. Git-backed wikis should publish through PRs or MRs and rerun lint before merge. For GitHub specifically, only changes on the default branch become live, so preview must happen before pushing or via a non-live mirror. MediaWiki writes should be revision-aware to avoid stomping on concurrent edits. Confluence changes should be staged through non-live locations or approval-bound publication steps rather than direct in-place mutation. Across all platforms, the publish job should re-run link, redirect, sitemap, llms, and security checks after publication and before marking the repair complete.

Security, Privacy, Testing, and Monitoring

The permissions model should be strict by default. Discovery should run with read-only credentials and writeback should require separate, more narrowly scoped credentials. Review, publish, export, and approval privileges should be separate roles, because LLMWikis’ security guidance explicitly distinguishes access control, redaction, public/private boundaries, agent permissions, audit logs, and human approval. For Confluence specifically, space permissions can be assigned to groups and individuals and narrower controls can apply at the page level, which means repair mode should ingest both space-level and page-level permissions before making remediations.

Privacy handling should be conservative. LLMWikis says sensitive materials such as credentials, privileged infrastructure details, raw customer or employee data, regulated records, and private meeting transcripts should not be stored or exported without explicit governance and redaction. Accordingly, repair mode should run secret and regulated-data scanning before export, suppress restricted pages from sitemap.xml and llms.txt, and generate only sanitized public artifacts. It should also obey robots rules when crawling public surfaces, while recognizing the formal Robots Exclusion Protocol limitation that robots.txt is not an access-control mechanism and should never be treated as authorization.

Testing should combine content, platform, and governance QA. At minimum, repair mode should have fixture-based adapter tests for every supported platform; golden tests for migration maps and patch bundles; metadata validation for required LLMWikis fields; navigation tests for orphan detection, breadcrumbs, related links, and redirects; discovery-surface tests for sitemap.xml and llms.txt; structured-data validation for canonical public pages; and security tests that confirm restricted pages never appear in public discovery files. That test matrix directly reflects the standards LLMWikis uses for metadata, navigation, linting, trust, and human review.

Monitoring should focus on drift rather than just uptime. Useful ongoing signals include inventory coverage deltas, newly orphaned pages, duplicate-canonical growth, stale-review backlog, ownerless authoritative pages, discovery-surface leakage, redirect failures, and post-repair 404s. Platform-native audit trails should be incorporated wherever possible: Confluence exposes audit-log records, GitHub wikis expose commit history because they are Git repositories, MediaWiki exposes revision-aware APIs and revision history, and DokuWiki’s file-based storage makes snapshot comparison straightforward.

Migration, Versioning, and Effort Model

Repair mode should version the repair itself, not just the repaired wiki. A complete run should produce an immutable crawl snapshot, a normalized page graph, a scorecard, a remediation plan, a migration map, generated discovery artifacts, and a post-publish validation report. That design matches the wizard’s structured-model output and the repair guide’s explicit requirement for a migration map that records old URL, new URL, action, redirect type, canonical target, and reason. It also makes rollback simpler because every publish can be tied back to a specific remediation manifest and artifact bundle.

The timeline below is a realistic v1 delivery sequence for an approval-gated repair mode with two or three platform adapters. It is an implementation estimate, not a published LLMWikis roadmap.

gantt
    title Suggested v1 delivery timeline for repair mode
    dateFormat  YYYY-MM-DD
    axisFormat  %b %d

    section Foundation
    Standards mapping and score model     :a1, 2026-06-01, 10d
    Input model and artifact schema       :a2, after a1, 7d

    section Platform adapters
    Git-based adapters                    :b1, 2026-06-08, 14d
    MediaWiki or DokuWiki adapter         :b2, 2026-06-15, 14d
    Confluence adapter                    :b3, 2026-06-22, 14d

    section Core engine
    Inventory and normalization           :c1, 2026-06-08, 14d
    Rule engine and migration map         :c2, 2026-06-22, 14d
    LLM-assisted classifiers              :c3, 2026-06-29, 10d

    section Product surface
    Wizard integration                    :d1, 2026-07-06, 10d
    Admin dashboard and approvals         :d2, 2026-07-14, 10d

    section Hardening
    Staging, rollback, and audit          :e1, 2026-07-21, 10d
    Pilot QA and tuning                   :e2, 2026-08-04, 10d

Rollback strategy must stay platform-aware. MediaWiki should be treated as needing both content export and full backup discipline, because XML export is useful but not a complete backup of the wiki’s database and files. DokuWiki’s file-copy backup model makes rollback comparatively simple. Confluence should be paired with pre-change exports and audit visibility. GitHub and GitLab benefit from Git-native rollback, but GitHub’s live-wiki constraint means preview should not depend on branch publication. Redirect deployment should be versioned alongside content patches so route rollbacks can be reversed together with content rollbacks.

The estimates below assume that core platform access has already been approved and that manual authority resolution for highly contested pages is tracked separately.

A durable staffing model usually needs six capabilities even if some are part-time: platform architecture, platform integration, frontend/dashboard, content and taxonomy design, QA/SDET, and security/privacy review. Regulated environments should also name human approvers from legal, security, privacy, or operations, because LLMWikis explicitly expects those approval boundaries to be visible when sensitive or high-risk updates are involved.

The most defensible delivery strategy is therefore phased. Phase one should analyze, score, and stage. Phase two should generate safe patch bundles and redirect maps. Phase three should add approval-gated writers for specific platforms. That sequencing stays aligned with LLMWikis’ current wizard boundary, preserves the two-step review model, and still produces immediate value by converting “repair” from a vague cleanup idea into a governed, testable migration workflow.