Note: This is a temporary planning document. It will be archived or converted to an ADR once the proposal is reviewed and decisions are made.

Proposal: An Enhanced, Automated Documentation Framework¶

1. Executive Summary¶

The current SyRF documentation framework is a best-in-class example of developer-led, in-repo documentation. It is highly structured, process-oriented, and well-integrated with the team's workflow. This proposal outlines a vision for enhancing this strong foundation by introducing a layer of intelligent automation and organizational improvements.

The goal is to reduce manual effort, improve discoverability, align with actual workflow patterns, and deepen the integration with LLMs, making the framework not just a repository of knowledge, but an active, intelligent partner in the development lifecycle.

Key findings:

The multi-repo strategy is optimally designed for LLM context and should be preserved
The /docs/features/ folder is completely empty despite excellent templates - the framework assumes "big features" but the team does "epic-driven initiatives"
Q&A iteration patterns are documented but never used - no templates or tooling exist
Manual maintenance burden causes inconsistencies despite excellent design
No place for external source documentation during feature planning

2. Analysis of the Current Framework¶

Strengths	Opportunities for Enhancement
✅ Highly Structured: Clear document types, templates, and lifecycle.	Automation of manual, repetitive tasks.
✅ Automation-Friendly: YAML front matter is perfect for machine processing.	Proactive scripts that act on YAML data, not just validate it.
✅ Process-Integrated: Excellent alignment with Scrum/ZenHub workflow.	Deeper, bi-directional sync between docs and ZenHub.
✅ Unified View: `mkdocs-monorepo-plugin` provides a single source of truth.	More dynamic and context-aware navigation.
✅ LLM-Aware: The project is explicitly designed for AI assistance.	Shifting LLMs from passive assistants to proactive agents.

3. Proposed Enhancements¶

This proposal is broken down into four key areas of improvement.

3.1. Workflow Automation: "Automate the Mundane"¶

The current framework relies on developer discipline. We can make the "right way" the "easy way" by automating common tasks.

A. CLI for Document Scaffolding¶

Concept: A simple, interactive CLI tool to bootstrap new documents.
Example Usage: syrf-cli docs new --type feature --title "User Profile Redesign"
Actions:
1. Creates the correct directory structure (e.g., /docs/features/user-profile-redesign/).
2. Generates README.md and technical-plan.md from the standard templates.
3. Pre-fills YAML front matter: author (from git config), created/updated dates, status: "Draft".
4. (Future) Could interact with the ZenHub API to create a placeholder Epic and link it (zenhub-ticket: "#...").

B. Automated Lifecycle Transitions¶

Concept: Use GitHub Actions to automatically update a document's status based on repository events.
Triggers & Actions:
PR Opened: When a PR is opened that creates a new feature doc, a bot could post a comment with a link to the rendered doc preview and remind the team to review.
PR Merged: When a feature branch is merged into main, a script could find the associated documentation (via branch name or PR description) and automatically update its status from Approved to Completed.
PR to cluster-gitops: When a promotion PR is created, the action could link back to the feature docs that are part of that release.

3.2. Enhanced Planning & Visualization: "Make Knowledge Discoverable"¶

We can transform static documentation into dynamic, explorable knowledge.

A. Automated Dependency & Architecture Visualization¶

Concept: Automatically generate and embed Mermaid.js diagrams from existing YAML data files.
Implementation:
1. A script (run via a make command or pre-commit hook) reads docs/architecture/dependency-map.yaml.
2. It generates a dependency-map.md file containing a Mermaid graph definition.
3. The MkDocs site automatically renders this into a visual dependency graph.
Benefit: The dependency map never becomes stale. Any change to the YAML is immediately reflected in the visualization.

B. Dynamic Roadmap Generation¶

Concept: Create a single, always-up-to-date roadmap page from the metadata of all feature documents.
Implementation:
1. A script scans all files in /docs/features/.
2. It parses the YAML front matter of each README.md.
3. It generates a /docs/roadmap.md file that groups features by their status (e.g., "In-Review", "Approved") and priority.
Benefit: Provides an instant, high-level overview of project momentum without manual updates.

3.3. Superior Navigability: "If You Can't Find It, It Doesn't Exist"¶

A. Automated Index Page Generation¶

Problem: The framework requires index.md files to be manually updated to link to all documents in a directory. This is tedious and error-prone.
Solution: A script that automatically generates these index pages.
Implementation:
1. A pre-build script for MkDocs traverses the docs directory.
2. In each subdirectory with an index.md, it updates the file to include a list of all other markdown files, pulling the title from each document's H1 tag or YAML title field.
Benefit: Navigation is always complete and accurate.

B. Knowledge Graph Visualization¶

Concept: Create an interactive, Obsidian-style knowledge graph of the entire documentation suite.
Implementation: Use a MkDocs plugin like mkdocs-obsidian-support or a custom script to parse inter-document links and tags to build a graph dataset (e.g., for D3.js).
Benefit: Allows developers to visually explore relationships between features, ADRs, and how-to guides, uncovering hidden dependencies and gaining a deeper understanding of the system's history and structure.

3.4. Proactive LLM Integration: "From Assistant to Agent"¶

We can empower LLMs to move beyond on-demand tasks and become proactive guardians of documentation quality.

A. AI-Powered Documentation Linter¶

Concept: A GitHub Action that runs on documentation changes and uses an LLM to provide qualitative feedback.
Checks:
Consistency: "This document refers to the 'Auth Service', but ADR-005 renamed it to the 'Identity Service'. Should you update this?"
Clarity & Style: "The 'Problem Statement' section is a bit vague. Consider adding a more concrete user scenario."
Completeness: "This Technical Plan doesn't mention a testing strategy. Should one be added?"

B. Automated Changelog Generation¶

Concept: When a feature's status is moved to Completed, trigger an LLM to draft a release note for the end-user documentation.
Workflow:
1. A GitHub Action detects the status: Completed change.
2. It provides the Feature Brief and Technical Plan to an LLM.
3. The prompt asks the LLM to generate a user-friendly summary suitable for the /user-guide/whats-new/ section.
4. The LLM creates a new draft file, which a developer can then review and finalize.

4. Phased Implementation Roadmap¶

This vision can be implemented incrementally.

Phase 1 (Quick Wins - This Sprint):
Script for Automated Index Page Generation.
Script for Automated Dependency Visualization (Mermaid from YAML).
Phase 2 (Core Automation - Next 1-2 Sprints):
Develop the interactive CLI for document scaffolding.
Implement GitHub Actions for automated lifecycle transitions (Draft -> Completed).
Phase 3 (Advanced Integration - Future):
Explore bi-directional ZenHub synchronization.
Implement the AI-powered documentation linter.
Set up the knowledge graph visualization.
Build the automated changelog generation workflow.

5. Feature Planning Enhancement: Q&A Iteration System¶

5.1. The Current Gap¶

The framework mentions Q&A files but provides no structure:

Q&A pattern documented in /docs/README.md and /docs/how-to/feature-planning-workflow.md
Zero Q&A files exist in the repository
No templates or iteration support
No LLM prompts for question generation

Introduce structured iterations for feature planning:

Iteration 1: Discovery (Scope & Users)¶

Who are the users?
What problem are we solving?
What does success look like?
What's the MVP vs future phases?

Iteration 2: Requirements (Acceptance Criteria)¶

What are the specific requirements?
What are the non-functional requirements?
What are the dependencies?
What are the constraints?

Iteration 3: Technical (Implementation)¶

How should this work technically?
What are the edge cases?
What are the risks?
What alternatives exist?

5.3. Q&A Template Structure¶

---
doc-type: "Discussion"
status: "Draft"
iteration: 1
feature: "{feature-name}"
---

# Q&A Session: {Feature Name} - Iteration {N}

## Session Metadata
- **Date**: YYYY-MM-DD
- **Iteration**: 1
- **Goal**: [What we're trying to clarify]

## Questions from Previous Iteration
[Summary if iteration > 1]

## New Questions

### Q1: [Category] - [Question]
**Context**: Why this matters
**Options**:
- [ ] Option A: Description
- [ ] Option B: Description
- [ ] Other (specify)

**Your answer**:
[Free text space]

## Ambiguities Identified
- [ ] Ambiguity 1
- [ ] Ambiguity 2

## Next Steps
- [ ] Create Feature Brief (if ready)
- [ ] Schedule next iteration (if needed)

6. External Source Documentation¶

6.1. The Need¶

During feature planning, teams often reference:

Third-party API documentation
Technical standards (OAuth2, OpenAPI)
Research papers or methodologies
Competitor analysis

Currently, there's no organized place for these references.

6.2. Proposed Structure¶

Create /docs/sources/ directory:

docs/sources/
├── README.md              # Purpose and lifecycle
├── apis/                  # Third-party API specs
│   ├── stripe-api.md
│   └── auth0-spec.md
├── standards/             # Technical standards
│   ├── oauth2-spec.md
│   └── openapi-3.0.md
├── research/              # Academic papers
│   └── prisma-guidelines.md
└── competitors/           # Competitor analysis
    └── covidence-features.md

6.3. Lifecycle Management¶

Add: When starting feature planning requiring external reference
Reference: Link from Feature Briefs and Technical Plans
Archive/Remove: After feature completes (keep if broadly useful)

YAML frontmatter for sources:

---
doc-type: "Reference"
status: "Active"
source-type: "API Spec"
source-url: "https://stripe.com/docs/api"
related-features: ["payment-integration"]
tags: ["external", "api", "payment"]
---

7. Multi-Repository Documentation Strategy¶

7.1. Current Structure Analysis¶

/home/chris/workspace/syrf/               # Main repo
├── docs/                                  # 30+ docs (primary hub)
├── cluster-gitops/                        # Nested, gitignored
│   └── docs/                              # 5 docs (deployment)
└── camarades-infrastructure/              # Nested, gitignored
    └── docs/                              # 5 docs (infrastructure)

Critical Insight: This structure is deliberately designed for LLM visibility

All repos accessible in single Claude Code context
No context switching needed for LLMs
Cross-repo references easy to follow

7.2. Evaluation: Keep Current Strategy¶

Verdict: ✅ The multi-repo strategy is optimal

Reasons:

"Documentation lives where action happens" - Correct separation of concerns
LLM-friendly - All visible in single working directory
Small, focused doc sets - Not overwhelming (5-10 docs per nested repo)
Unified publishing - MkDocs monorepo plugin works seamlessly
Clear ownership - No ambiguity about where docs belong

7.3. Minor Optimizations¶

Create navigation aids:

/docs/architecture/documentation-map.md - Quick reference by topic
/docs/architecture/llm-navigation-guide.md - For AI assistants

8. Automation with GitHub MCP and Claude¶

8.1. Available GitHub MCP Functions¶

The project already has GitHub MCP configured with:

mcp__github__issue_read/write - Issue management
mcp__github__sub_issue_write - Parent/child relationships
mcp__github__search_issues - Complex queries
mcp__github__pull_request_* - PR operations
mcp__github__create_or_update_file - Remote file ops

8.2. Markdown ↔ GitHub Issues Sync¶

Data Model¶

# Markdown frontmatter
---
github-issue: "#2128"
sync-enabled: true
last-sync: "2025-11-21"
---

## Epic: GitOps Migration
### Work Item 1: Foundation
**GitHub Issue**: #2129
**Status**: ✅ Complete
**Story Points**: 8

Implementation Pattern¶

def sync_backlog_to_github():
    backlog = read_file("docs/planning/backlog.md")
    work_items = parse_work_items(backlog)

    for item in work_items:
        if item.github_issue:
            mcp__github__issue_write(
                method="update",
                issue_number=item.github_issue,
                title=item.title,
                state=map_status(item.status)
            )
        else:
            issue = mcp__github__issue_write(
                method="create",
                title=item.title,
                labels=["work-item"]
            )
            update_markdown(item.id, issue.number)

8.3. Claude Skills for Documentation¶

Create specialized skills:

feature-backlog-sync - Parse markdown, create/update GitHub Issues
auto-doc-updater - Update docs on deployment
cross-ref-validator - Validate links and references
feature-planner - Guide iterative Q&A sessions

9. Implementation Roadmap¶

Phase 1: Quick Wins (Week 1-2) ✅ COMPLETED¶

Fix YAML frontmatter inconsistencies - All 53 docs now compliant
Create Q&A iteration template - Created with 3-iteration structure
Create sources directory structure - Created as research staging area
Add documentation navigation maps - Created documentation-map.md and llm-navigation-guide.md

Phase 2: Automation Foundation (Week 3-4) ✅ COMPLETED¶

Document scaffolding CLI - Deferred to Phase 3
Pre-commit hooks for validation - Created with markdownlint and yamllint
CI/CD validation integration - GitHub Actions workflow with PR comments
Automated index generation - Script generates indexes for all subdirectories

Phase 3: Sync Implementation (Month 2) ⏳ IN PROGRESS¶

Create feature-backlog-sync skill - Comprehensive skill for GitHub/ZenHub sync
Test with migration backlog - Analyzed 16 "In Progress" issues, 0% coverage identified
Add scheduled sync workflows - Weekly reminder workflow created
Post-deployment doc updates - Deferred pending ArgoCD production deployment

Phase 4: Advanced Features (Month 3+)¶

LLM-powered Q&A sessions
Documentation quality scoring
Metrics dashboard
ZenHub bidirectional sync

10. Success Metrics¶

Metric	Current	Target (3 months)
Features folder usage	0 docs	10+ features
YAML compliance	~60%	100%
Automation coverage	0%	70%
Average doc freshness	Unknown	<3 months
GitHub Issues sync accuracy	N/A	95%+

11. Key Recommendations¶

Don't redesign, enhance - The framework design is excellent, execution needs automation
Keep multi-repo strategy - It's optimal for LLM context
Support epic-driven work - Not just "big features"
Add Q&A iteration - Progressive refinement with LLM assistance
Create sources directory - Organized external documentation
Automate the mundane - Make the "right way" the "easy way"

12. Next Steps¶

This document serves as a comprehensive analysis and proposal for discussion. The team is invited to:

Review the multi-repo strategy evaluation
Prioritize the implementation phases
Test Q&A iteration templates with next feature
Decide on automation tooling (CLI, skills, workflows)

The combination of Gemini's original automation vision and Claude's detailed analysis provides a complete picture of how to evolve the documentation framework while preserving its excellent foundation.