📝 Documentation Write Agent Specification¶

📌 Purpose¶

The Documentation Write Agent is responsible for transforming structured knowledge outputs into high-quality, traceable, edition-aware technical documentation — written in the ConnectSoft tone, format, and style.

It ensures that every artifact produced by the factory — whether from a Developer Agent, Test Generator, Architect Agent, or Bug Resolver — is:

🧾 Documented, explained, visualized, and ready for consumption by developers, stakeholders, AI agents, and external tools.

🎯 Primary Goals¶

Goal	Description
📄 Generate human-readable documentation	Converts agent outputs into well-formatted `.md`, `.yaml`, or `.json` files
🧠 Enrich context from memory	Retrieves related knowledge to cross-link documentation
🪄 Maintain tone & structure	Follows ConnectSoft writing style: clear, modular, edition-aware
🧾 Enable traceability	Each doc includes `traceId`, `agentId`, `sourceArtifactId`, and `editionId`
📚 Serve as input for other agents	Provides documentation for Studio Agent, Generator Agent, and QA workflows

🧩 Key Use Cases¶

Case	Outcome
✅ After MicroserviceGeneratorAgent emits a new service	Creates `/docs/modules/<service>/README.md`
🔍 After TestGeneratorAgent emits `.feature` files	Creates test overview, scenario descriptions, and QA metadata pages
🧠 After Bug Resolver Agent proposes a fix	Converts `fix-summary.md` into structured changelogs
📊 After Vision Architect defines features	Writes `/docs/features/<feature>/blueprint.md` from trace plan
⚙️ After Architecture Agents update diagrams	Updates `/docs/architecture/` with rendered diagrams and explanations

📘 Typical Output Types¶

Output	Description
`README.md`	Main module documentation page
`fix-summary.md`	Summary of bug fix, linked to fingerprintId
`feature-blueprint.md`	Vision/feature spec from planning phase
`test-plan.md`	QA test overview generated from `.feature` files
`architecture-overview.md`	High-level platform or cluster docs
`studio.preview.json`	Structured metadata for Studio dashboard tiles

🧠 Agent Class & Personality¶

Trait	Description
🧾 Narrative-first	Turns structured agent outputs into fluent, informative narratives
📐 Structurally aware	Understands headers, lists, tables, code blocks, diagrams
📚 Knowledge-linked	Cross-links trace paths, modules, and memory-embedded knowledge
🧠 Edition-aware	Scopes output to specific editions (`vetclinic`, `multitenant-lite`, etc.)
🤖 Collaboration-friendly	Invoked by agents or users via trace or MCP prompt contexts

🧭 System Role¶

flowchart TD
    GEN[🧠 Generator Agents]
    TEST[🧪 Test Generator Agent]
    BUG[🛠️ Bug Resolver Agent]
    DOC[📝 Documentation Write Agent]
    KM[🧠 Knowledge Management Agent]
    STUDIO[📊 Studio Agent]

    GEN --> DOC
    TEST --> DOC
    BUG --> DOC
    DOC --> KM
    DOC --> STUDIO

Hold "Alt" / "Option" to enable pan & zoom

✅ Summary¶

The Documentation Write Agent:

📄 Converts internal AI outputs into developer-facing, test-ready documentation
🔗 Ensures each document is trace-linked, memory-aware, and reusable
🧠 Supports other agents with readable artifacts, changelogs, diagrams, and storyboards
⚙️ Scales across editions, modules, and services, generating docs dynamically
📊 Powers Studio and external dashboards with renderable previews and metadata

It is the voice of the AI Factory — ensuring that autonomous outputs are visible, verifiable, and valuable to humans and agents alike.

📋 Responsibilities¶

This section outlines the explicit responsibilities of the Documentation Write Agent. These define how it contributes to the ConnectSoft AI Software Factory by turning structured agent output into narrative, visual, and modular documentation.

✅ Core Responsibilities¶

Responsibility	Description
🧾 Generate Markdown Documentation	Converts agent outputs (traces, blueprints, test plans, fix summaries) into well-structured `.md` documents
🧠 Retrieve Context from Memory	Enriches documentation with knowledge entries, trace metadata, and relevant artifact links
🔗 Embed Traceability	Automatically includes `traceId`, `artifactId`, `agentId`, and `editionId` in generated docs
🧰 Apply Doc Templates	Uses semantic Markdown templates for features, services, modules, bug summaries, architecture overviews, etc.
🧩 Modularize Output	Splits docs by module, feature, or agent cluster into reusable sub-sections or linked index files
📎 Attach Diagrams	Includes inline Mermaid diagrams or references to `.svg` and `.png` architecture visuals
🧾 Emit Studio Preview Artifacts	Outputs `studio.preview.json` for dashboard tiles, code previews, or status badges
🧠 Summarize Structured YAML or JSON	Converts raw inputs like `test-results.json`, `bug-resolution.yaml`, `feature-plan.yaml` into readable narratives
📚 Conform to Style Guide	Applies tone, structure, and branding rules consistent with ConnectSoft documentation style
🛠️ Auto-link Artifacts	Cross-links related docs, GitHub paths, tests, microservices, and trace cluster summaries

🧾 Supported Artifact Types¶

Input Source	Output Target
`trace.plan.yaml`	`blueprint.md` (feature or capability doc)
`bug-resolution.yaml` + `fix-summary.md`	`fix-report.md` (changelog with reasoning)
`README.template.md` + service info	`README.md` per microservice
`.feature` + test metadata	`test-plan.md`, `qa-index.md`, `scenario-details.md`
Architecture diagrams (`.mmd`, `.svg`)	`architecture-overview.md`, `mermaid-preview.md`
Prompt blueprints (`.prompt`, `.template.yaml`)	`prompt-library.md`, `agent-instruction.md`

🛠️ Post-Processing Duties¶

Task	Purpose
✅ Linting	Validate Markdown headings, table consistency, and format correctness
🔗 Link rewriting	Ensure relative links between modules, editions, or sections resolve properly
🧠 Anchor tagging	Automatically add anchor IDs for Studio scroll targeting and TOC generation
📂 Folder layout enforcement	Output organized by edition → domain → cluster → artifact type
🧑‍💻 Markdown component injection	Add tabs, toggles, notes, tips via ConnectSoft-styled extensions
📊 Studio status generation	Output `studio.bug.status.json`, `studio.module.preview.json` for visual integration

🧩 Role in Documentation Lifecycle¶

flowchart TD
    PLAN[📊 Planning Agent]
    GEN[🧠 Generator Agent]
    TEST[🧪 Test Generator Agent]
    BUG[🛠️ Bug Resolver Agent]
    DOC[📝 Documentation Write Agent]
    KM[🧠 Knowledge Management Agent]
    STUDIO[📊 Studio Agent]

    PLAN --> DOC
    GEN --> DOC
    TEST --> DOC
    BUG --> DOC
    DOC --> KM
    DOC --> STUDIO

Hold "Alt" / "Option" to enable pan & zoom

✅ Summary¶

The Documentation Write Agent is responsible for:

🧾 Writing traceable, readable, and edition-scoped documentation
🔄 Automating the full transformation from structured input → human-facing docs
📎 Linking memory, trace, module, and fix metadata across all agents
🧩 Powering Studio previews, changelogs, module READMEs, test plans, and visual diagrams
💡 Ensuring that ConnectSoft’s autonomous outputs are comprehensible, navigable, and production-grade

📥 Inputs Consumed¶

This section outlines the structured and semi-structured inputs the Documentation Write Agent consumes from other agents and source artifacts to produce comprehensive, traceable documentation.

📂 Primary Input Artifacts¶

File	Source Agent	Description
`trace.plan.yaml`	Vision Architect Agent	Feature or capability blueprint — foundation for feature docs
`feature.spec.json`	Product Owner Agent	Structured user stories and scenarios to convert into narrative specs
`bug-resolution.yaml` + `fix-summary.md`	Bug Resolver Agent	Input for fix changelogs and explanation documentation
`test-results.json`	QA Agent	Test results, pass/fail matrix, and scenario grouping
`.feature` files	Test Generator Agent	BDD-style specs, mapped into test plan documents
`README.template.md`	Microservice Generator Agent	Base template for service documentation
`prompt.plan.yaml`	Prompt Architect Agent	Used for documenting AI instruction flows and prompt inheritance
`architecture-overview.mmd` or `.svg`	Architecture Agents	Visual representation of components, clusters, and flows

📘 Example: `trace.plan.yaml`¶

featureId: notify-clients-after-booking
agentsInvolved:
  - ProductManagerAgent
  - MicroserviceGeneratorAgent
  - NotificationPlannerAgent
modulesAffected:
  - NotificationService
  - EmailService
capabilities:
  - trigger confirmation email
  - fallback to SMS
documentation:
  overview: true
  generateFeatureDoc: true
  edition: vetclinic

→ Triggers feature-blueprint.md in /docs/features/notify-clients-after-booking/

📘 Example: `bug-resolution.yaml`¶

fingerprintId: bug-5521b
fixType: addNullCheck
module: Appointments
edition: vetclinic-premium
confidenceScore: 0.91
resolutionStatus: proposed
patchFile: proposed-fix.diff

→ Used to write fix-report.md with summary and linked patch.

🔄 Dynamic Inputs (via Skill Context or Vector Search)¶

Input	Description
`memory-entry.json`	Embedded documents used for references, summary, and cross-linking
`knowledge-index.yaml`	Helps group documents by agent, capability, or module
`traceId` + `artifactId`	Passed via `SKContext`, used to embed traceability headers
`editionId`	Ensures doc output respects edition scoping (e.g., lite vs. enterprise)

🧠 Semantic Kernel Input Context¶

Variable	Purpose
`SKContext["documentType"]`	Controls which template is selected
`SKContext["artifactTraceId"]`	Ensures document is trace-linked
`SKContext["agentCluster"]`	Helps classify the doc into architecture, engineering, QA, planning, etc.
`SKContext["rawInput"]`	Structured artifact body used for summarization, formatting, or rewriting
`SKContext["injectMemoryReferences"]`	Flag to append related docs and knowledge entries at the bottom

📎 Inputs from Studio Agent¶

File	Use
`studio.style.config.json`	Branding and layout rules (e.g., callouts, heading structure, links)
`studio.annotation.yaml`	Human-injected descriptions or overrides for ambiguous sections
`studio.preview.config.yaml`	Triggers for preview rendering, coverage dashboards, and module highlights

✅ Summary¶

The Documentation Write Agent consumes inputs from:

📄 Planning artifacts (trace.plan.yaml, feature.spec.json)
🧪 QA and Bug reports (fix-summary.md, test-results.json)
🧠 Memory entries, edition overlays, and trace metadata
🧾 Generator Agent outputs (README.template.md, .feature)
🧩 Architecture diagrams and prompt plans for visual and prompt docs

This input mesh allows the agent to generate rich, accurate, and trace-linked documentation for every ConnectSoft artifact and edition.

📤 Outputs Produced¶

This section defines the structured documentation artifacts generated by the Documentation Write Agent. These outputs are written in Markdown, YAML, and JSON, optimized for both human readers and downstream agent/tool consumption.

📄 Markdown Documentation Outputs¶

File	Purpose
`README.md`	Main documentation for a microservice, module, or agent output
`feature-blueprint.md`	Description of a feature or capability from trace planning
`fix-report.md`	Narrative explanation of a bug fix (sourced from `fix-summary.md`)
`test-plan.md`	Summary of generated tests and associated `.feature` specs
`architecture-overview.md`	Documented diagrams and architecture flows with embedded Mermaid or SVG
`prompt-library.md`	Library of prompts and templates used by agents (e.g., ProductManagerAgent)
`studio-guides.md`	Descriptions of how to use Studio dashboard views, metrics, or annotations
`module-index.md`	Index of documentation pages for a module or cluster (e.g., QA, Engineering)

🧾 YAML / JSON Metadata Outputs¶

File	Purpose
`documentation.index.yaml`	Structured index of generated documents (by traceId, moduleId, edition)
`studio.preview.json`	Supplies Studio with preview title, summary, badges, agent IDs, and status flags
`trace-doc-map.yaml`	Maps trace paths to documentation files (traceId → doc output)
`doc-coverage.metrics.json`	Captures documentation coverage across agents, editions, and clusters

📘 Example: `README.md` (Microservice)¶

# Notification Service

This service handles client communication via email, SMS, and push.

## Capabilities
- Send confirmation messages after appointments
- Fallback to SMS if email fails
- Localized per edition: `vetclinic`, `multitenant-lite`

## Trace Info
- `traceId`: proj-901-notify
- Generated by: MicroserviceGeneratorAgent
- Maintained by: NotificationPlannerAgent

📘 Example: `fix-report.md`¶

# 🛠️ Fix Report: Cancel Appointment Modal

- **Fingerprint**: bug-a1c02d34
- **Classification**: Flaky UI Test
- **Fix Strategy**: `waitForVisible("confirmation-modal", 1000ms)`
- **Edition**: `vetclinic-premium`
- **Confidence**: 94%
- **Patch Size**: 2 lines

## Resolution Summary
The modal was rendered with a race condition. The fix delays assertion using a visible-wait strategy to stabilize test execution.

📎 Studio Preview Output Example (`studio.preview.json`)¶

{
  "traceId": "proj-811-v1",
  "document": "feature-blueprint.md",
  "previewTitle": "Notify Clients After Booking",
  "tags": ["feature", "planning", "notification"],
  "status": "documented",
  "agentId": "VisionArchitectAgent"
}

🧠 Cross-Linked Output¶

Each generated file:

📌 Contains traceId, agentId, moduleId, editionId headers
🔗 Links to related .diff, .feature, .yaml, .md files via local relative references
🧠 May embed retrieved memory-entry.json summaries or architecture annotations
📊 Supports Studio dashboard rendering, CI inclusion, and multi-edition overlays

✅ Summary¶

The Documentation Write Agent emits a complete set of:

📝 Markdown documentation pages for features, modules, tests, and fixes
🧾 YAML/JSON indexes and metadata for trace, preview, and coverage reporting
🔗 Trace-linked artifacts for downstream agents, Studio dashboards, and developer teams

These outputs ensure that every ConnectSoft-generated capability, plan, test, and fix is documented, linked, and ready for delivery or review.

🧠 Knowledge Base¶

This section outlines the embedded knowledge that powers the Documentation Write Agent’s ability to generate accurate, structured, and style-consistent documentation across all ConnectSoft artifacts, modules, and editions.

📚 Pretrained & Embedded Knowledge¶

Domain	Description
🧾 ConnectSoft Documentation Style Guide	Markdown formatting, headings, tables, language tone, callouts, etc.
🧩 Doc Template Library	Predefined templates for `README.md`, `feature-blueprint.md`, `test-plan.md`, `fix-report.md`, etc.
📘 Agent Responsibilities and Output Contracts	Understands the roles and output structures of every system agent (e.g., Bug Resolver Agent → `fix-summary.md`)
🧠 Modular Doc Layout Patterns	Best practices for organizing docs per module, edition, agent cluster
📊 Studio Tile Rendering Rules	Generates `studio.preview.json` with correct format, status, and tags
🗂️ Project Folder Conventions	Knows where to place docs: `/docs/modules/`, `/docs/features/`, `/docs/fixes/`, etc.
🧠 Traceability Grammar	Automatically includes trace metadata and links to `traceId`, `agentId`, `editionId`, etc.

📁 Examples of Internal Templates¶

✅ `feature-blueprint.md` Template¶

# {{FeatureTitle}}

> This document was generated by the Documentation Write Agent using trace `{{traceId}}`.

## Overview
{{FeatureSummary}}

## Capabilities
- {{capability1}}
- {{capability2}}

## Modules Affected
- {{moduleA}}
- {{moduleB}}

## Agent Collaboration
{{AgentDiagram}}

✅ `fix-report.md` Template¶

# 🛠️ Fix Report: {{BugTitle}}

- **Fingerprint**: {{fingerprintId}}
- **Fix Type**: {{fixType}}
- **Edition**: {{editionId}}
- **Confidence**: {{confidenceScore}}%
- **Patch Summary**: {{summary}}

## Root Cause
{{RootCauseExplanation}}

## Fix Details
{{PatchExplanation}}

🧠 Pattern-Matching Capabilities¶

Trigger	Response
`.feature` file with `Scenario:`	Converts to a Markdown test plan with a list of scenarios
`bug-resolution.yaml` + `fix-summary.md`	Triggers fix changelog generation with strategy and root cause explanation
`trace.plan.yaml` with `generateFeatureDoc: true`	Auto-generates blueprint with capabilities and agent involvement

🔁 Memory-Aware Composition¶

The agent retrieves:

memory-entry.json to embed summaries or historical references
knowledge-index.yaml to build cross-links between features/modules
trace-link-map.json to construct breadcrumb paths and related artifact links

📘 Example:¶

Given traceId: proj-821-ai-prompting → auto-links:

prompt-library.md
prompt-plan.yaml
agent-instruction.md
studio.preview.json

🧾 Prebuilt Markdown Components¶

Component	Purpose
`:::tip` blocks	Inserted for notes and best practices
Mermaid diagrams	Rendered automatically if `.mmd` provided
Edition badges	Auto-generated at top of document (`vetclinic-premium`)
Feature dependency lists	Rendered as collapsible trees if `dependsOn` detected

✅ Summary¶

The Documentation Write Agent already knows:

📄 How to structure docs by artifact type, trace, and edition
📚 What templates, layouts, and components to use for each scenario
🔗 How to enrich content with traceable, memory-linked context
📊 How to prepare output for Studio, CI, and human readers

This embedded knowledge gives the agent the power to generate professional, consistent, and deeply integrated documentation — automatically.

🔄 Process Flow (High-Level)¶

This section presents the high-level workflow of the Documentation Write Agent — showing how it moves from raw structured inputs to complete, cross-linked, edition-aware documentation artifacts.

📊 High-Level Flow Diagram¶

flowchart TD
    INPUT[📥 Receive Input Artifact]
    CONTEXT[🧠 Retrieve Trace & Memory Context]
    TEMPLATE[📄 Select Doc Template]
    COMPOSE[📝 Generate Markdown Content]
    ENRICH[🔗 Link, Annotate, Format]
    VALIDATE[✅ Lint + Trace Validation]
    OUTPUT[📤 Emit .md + .json + .yaml]

Hold "Alt" / "Option" to enable pan & zoom

🧩 Phases Overview¶

1. 📥 Input Received¶

Triggered by input artifact (e.g., trace.plan.yaml, .feature, fix-summary.md)
May also be triggered by agent event (FixProposed, FeaturePlanned)
traceId, agentId, and editionId must be present

2. 🧠 Retrieve Context¶

Access memory-entry.json, trace-link-map.yaml, and knowledge-index.yaml
Embeds relevant history, tags, capabilities, or changelogs

3. 📄 Select Template¶

Chooses the correct Markdown template based on:
- Document type (e.g., feature, fix, module)
- Agent cluster (QA, Engineering, Planning)
- Edition (editionId)
- Role (e.g., README, test-plan, blueprint)

4. 📝 Generate Content¶

Fills template with structured data from the input
Adds summaries, listings, capability tables, or scenario sections
Optionally injects Mermaid diagrams or YAML blocks inline

5. 🔗 Enrich Output¶

Adds:
- traceId, agentId, editionId headers
- Breadcrumbs
- Cross-links to related .md, .diff, or .feature files
Applies tone, structure, and branding

6. ✅ Validate¶

Lints Markdown
Confirms traceability and edition scope
Outputs doc-coverage.metrics.json for Studio

7. 📤 Emit Output¶

Writes to:
- README.md, fix-report.md, feature-blueprint.md, etc.
- studio.preview.json
- documentation.index.yaml

📘 Example Trigger Flow: Feature Plan¶

Input: trace.plan.yaml
↓
Memory Loaded: vision plan, related capabilities
↓
Template: feature-blueprint.md
↓
Output:
- /docs/features/notify-clients/feature-blueprint.md
- /docs/features/notify-clients/studio.preview.json

✅ Summary¶

The high-level flow of the Documentation Write Agent is:

📥 Trigger →
🧠 Enrich →
📄 Select Template →
📝 Compose →
🔗 Link →
✅ Validate →
📤 Emit

This makes the agent a deterministic, context-aware, and style-aligned content generator for all ConnectSoft documentation layers.

🔬 Process Flow (Detailed)¶

This section expands the agent's workflow into a step-by-step, skill-driven, memory-augmented pipeline, revealing how the agent turns structured inputs into professional documentation while ensuring full traceability, edition-scoping, and downstream compatibility.

🔁 Detailed Workflow Steps¶

flowchart TD
    A[📥 Input Artifact Received] --> B[🧠 Retrieve Trace Context]
    B --> C[🔍 Search Knowledge Memory]
    C --> D[📄 Select Template (by Doc Type)]
    D --> E[🧠 Compose Raw Draft from Structured Data]
    E --> F[🔗 Enrich with Links, Badges, Diagrams]
    F --> G[✅ Lint + Structure Validator]
    G --> H[📤 Emit Markdown, JSON, YAML]

Hold "Alt" / "Option" to enable pan & zoom

🧩 Detailed Step Breakdown¶

1. 📥 Input Artifact Received¶

Input types include:
- trace.plan.yaml
- feature.spec.json
- bug-resolution.yaml
- .feature files
SKContext populated with:
- traceId, editionId, agentCluster, documentType

2. 🧠 Retrieve Trace Context¶

Loads from:
- trace-link-map.yaml
- knowledge-index.yaml
- memory-entry.json
Adds cross-references for:
- Related features
- Modules
- Other docs

3. 🔍 Memory Query (Optional)¶

Uses SimilaritySearchSkill to enrich docs with:
- Fix patterns
- Prompt examples
- Architectural precedents

4. 📄 Template Selection¶

Chooses .md template from:
- feature-blueprint.md
- test-plan.md
- fix-report.md
- prompt-library.md
Template includes:
- Static headers
- Markdown tables
- Callouts
- Inline Mermaid or YAML blocks

5. 🧠 Compose Draft¶

Injects:
- Summaries
- Key-value tables
- Edition-scoped notes
- Agent responsibility sections
Applies SK skills for:
- Summarization
- YAML-to-Markdown rendering
- Scenario extraction

6. 🔗 Enrich Draft¶

Adds:
- traceId, editionId, agentId
- Cross-links to .diff, .feature, .md, .json
- Callouts (e.g., :::tip, :::warning)
- Mermaid rendering for diagrams if .mmd detected

7. ✅ Validate Output¶

Runs:
- Markdown linter
- Internal TOC validator
- Broken link checker
Outputs:
- doc-coverage.metrics.json
- documentation.index.yaml (updated or appended)

8. 📤 Emit Final Artifacts¶

Files written to:
- /docs/features/<featureId>/feature-blueprint.md
- /docs/modules/<moduleId>/README.md
- /docs/fixes/<fingerprintId>/fix-report.md
Also emits:
- studio.preview.json
- studio.status.yaml

✅ Example: Test Plan Generation¶

flowchart TD
    F1[.feature + test-results.json]
    F1 --> T1[Classify Scenarios]
    T1 --> T2[Summarize Steps]
    T2 --> T3[Template Injection: test-plan.md]
    T3 --> Output[/docs/tests/<module>/test-plan.md]

Hold "Alt" / "Option" to enable pan & zoom

✅ Summary¶

The Documentation Write Agent uses a structured, memory-aware, and modular composition pipeline that:

🧠 Leverages memory and trace context
📝 Generates trace-linked Markdown documentation
🔗 Embeds cross-doc relationships
🧾 Outputs metadata and previews for Studio and CI/CD tools
✅ Validates consistency, structure, and coverage

This makes it a production-ready AI doc writer that scales across services, clusters, and editions.

🧩 Skills & Kernel Functions Used¶

This section outlines the Semantic Kernel skills and core functions the Documentation Write Agent relies on to convert structured data into traceable, readable, and style-consistent Markdown documentation.

Each skill is modular, observable, and optionally reusable across other agents (e.g., Studio Agent, Knowledge Management Agent).

🧠 Core Semantic Kernel Skills¶

Skill Name	Description
`MarkdownComposerSkill`	Generates body content from structured input using Markdown templates and injected YAML/JSON
`DocumentTemplateSelectorSkill`	Selects the correct `.md` template based on input type, trace, and edition
`TraceMetadataFormatterSkill`	Formats `traceId`, `agentId`, `editionId`, and module metadata into frontmatter or doc headers
`MemoryLinkingSkill`	Retrieves similar entries from `memory-entry.json` or `knowledge-index.yaml` for inline referencing
`ScenarioSummarizerSkill`	Converts `.feature` test scenarios into summarized test plans or scenario listings
`FixSummaryFormatterSkill`	Translates `fix-summary.md` and `bug-resolution.yaml` into a readable `fix-report.md` format
`MermaidRendererSkill`	Converts `.mmd` to inline diagram blocks or links to SVG previews
`DocLinterSkill`	Ensures output matches Markdown structure, heading depth, and style guide rules

📘 Example: `MarkdownComposerSkill`¶

You are writing developer-facing documentation for a feature in the ConnectSoft platform.

Using the following YAML input, generate a Markdown document:

Input:
- featureId: notify-clients
- traceId: proj-888
- edition: vetclinic
- capabilities:
  - send email after booking
  - fallback to SMS

Output:
# Notify Clients (Feature Blueprint)

> Trace: proj-888 | Edition: vetclinic

## Capabilities
- send email after booking
- fallback to SMS

🔁 Cross-Skill Orchestration Example¶

flowchart TD
    A[trace.plan.yaml] --> B[DocumentTemplateSelectorSkill]
    B --> C[MarkdownComposerSkill]
    C --> D[MemoryLinkingSkill]
    D --> E[TraceMetadataFormatterSkill]
    E --> F[DocLinterSkill]
    F --> G[📤 Emit Markdown + Preview JSON]

Hold "Alt" / "Option" to enable pan & zoom

🧩 Utility Functions¶

Function	Description
`InjectEditionBadge()`	Adds edition-aware callout at top of document
`GenerateTOC()`	Creates or updates Table of Contents block based on headers
`GeneratePreviewSummary()`	Extracts first paragraph or caption for `studio.preview.json`
`ResolveLocalLinks()`	Converts paths like `../fixes/bug-123.md` into full trace-safe relative links

📎 Exposed for Other Agents¶

Agent	Uses
Studio Agent	Uses `MarkdownComposerSkill`, `TraceMetadataFormatterSkill` for inline previews
Knowledge Management Agent	May use `MemoryLinkingSkill` to backfill tags or doc annotations
Bug Resolver Agent	Delegates summary generation to `FixSummaryFormatterSkill`
Prompt Architect Agent	Uses `MarkdownComposerSkill` for generating `prompt-library.md` and `instruction.md`

✅ Summary¶

The Documentation Write Agent is powered by a rich set of Semantic Kernel skills that:

📝 Compose Markdown content from structured trace and metadata
🔗 Inject cross-agent, cross-module memory references
🧠 Apply trace metadata, tone, and edition-specific formatting
✅ Validate output format, structure, and style compliance
📤 Emit ready-to-publish content for developers, dashboards, and downstream agents

This skill set makes the agent modular, composable, and fully pluggable in the ConnectSoft documentation lifecycle.

🛠️ Technology Stack¶

This section describes the technology stack and runtime architecture used by the Documentation Write Agent, aligning with ConnectSoft’s clean architecture, modularity, and cloud-native principles.

💻 Core Stack¶

Layer	Technology
Runtime	.NET 8 + C#
AI Integration	Semantic Kernel (`Microsoft.SemanticKernel`)
LLM Provider	Azure OpenAI (GPT-4, `text-davinci-003`, `gpt-4-32k`)
Prompt Templating	SK YAML Prompt Format + inline `.prompt` files
Template Storage	Markdown templates in `/Templates/Markdown/*.md`
Memory Access	Azure Blob Storage, vector memory, or memory-entry JSON
Doc Output	Filesystem + blob push (`docs/` folder) + Studio preview publishing
Diagrams	Mermaid.js (`.mmd`), inline SVG, or external renderer

🧠 Memory and Trace Infrastructure¶

Component	Role
`memory-entry.json`	Source of knowledge for enrichment, tagging, and trace explanation
`trace-link-map.yaml`	Links trace paths to modules, capabilities, and related documentation
`knowledge-index.yaml`	Lists memory units for reuse, doc enhancement, and cross-linking
`studio.preview.json`	Output consumed by Studio dashboards and review tools

📘 Output File Types¶

Format	Use
`.md`	Human-readable technical documentation (main output)
`.json`	Previews for Studio tiles (e.g., title, tags, edition, agent)
`.yaml`	Indexes, trace maps, and linked documentation graphs

🧰 Markdown Tooling¶

Feature	Tool
Markdown linting	Built-in SK `DocLinterSkill` or Markdig extensions
Diagram rendering	Mermaid + optional integration with GitHub, Docusaurus, or Studio renderer
Markdown component support	`:::tip`, `:::note`, tab blocks (styled via Studio Markdown theme engine)

🛡️ Clean Architecture Enforcement¶

Concern	Approach
🧱 Separation of Concerns	Agent logic, SK skills, and IO writers live in separate layers
🔌 Pluggability	Markdown templates, styles, and language rules can be swapped per edition or cluster
🧾 Testability	Skills and output validators tested via unit/integration tests (e.g., test plan to Markdown validation)
🌐 Multi-edition safe	Every output is scoped by `editionId` with partitioned folders or file blocks

📡 Observability and CI/CD Integration¶

Tool	Description
Application Insights	Logs Markdown generation steps, failures, retries
OpenTelemetry	Traces each SK skill and output phase (e.g., Compose → Lint → Emit)
CI Pipeline Support	Output verified and previewed via Studio deployment checks or `lint-docs` step
Studio Integration	Hooks into Studio UI with preview tiles, summary diffs, and versioned doc review panels

🔁 Reusability Across Agents¶

Component	Reused By
`MarkdownComposerSkill`	Studio Agent, Knowledge Management Agent, Prompt Architect Agent
`TraceMetadataFormatterSkill`	Developer Agent, Fix Generator Agent
`MemoryLinkingSkill`	All memory-enhanced agents (e.g., Generator, Reviewer, QA Planner)

✅ Summary¶

The Documentation Write Agent is built on a modular, AI-enhanced, markdown-centric tech stack that supports:

✅ Semantic Kernel + Azure OpenAI for intelligent doc generation
📄 Clean Markdown, YAML, JSON outputs for developer and agent consumption
🔌 Studio-integrated previews, badges, and cross-agent linking
🌍 Multi-edition compatibility and trace-linked safety
📊 Observability-first execution with full telemetry

This makes the agent robust, testable, reusable, and scalable — the documentation backbone of the ConnectSoft platform.

🧾 System Prompt¶

This section defines the System Prompt used to initialize the Documentation Write Agent during execution. The prompt encodes its tone, structure, formatting rules, traceability requirements, and ConnectSoft documentation principles.

📘 System Prompt (Template)¶

You are the Documentation Write Agent in the ConnectSoft AI Software Factory.

Your task is to generate clear, structured, and traceable technical documentation from structured input artifacts created by other AI agents.

You must:
- Follow ConnectSoft’s documentation style guide: professional, modular, and Markdown-based
- Use structured headers (H1–H3), bullet points, tables, and Mermaid diagrams when applicable
- Always include trace metadata: traceId, agentId, editionId, moduleId
- Generate only documentation formats: `.md`, `.json`, or `.yaml`
- Preserve edition-scoping and label documents accordingly
- Reuse memory when helpful — link to related modules, features, or fixes

Acceptable input includes:
- `trace.plan.yaml`, `feature.spec.json`, `.feature`, `bug-resolution.yaml`, `prompt.plan.yaml`, test logs
- Input always includes a `traceId` and `documentType`

You must output:
- Markdown documentation with clear section headings and relevant summaries
- Optional Studio preview metadata (in JSON)
- YAML indexes or doc coverage updates if needed

Important:
- Do not generate unverified speculation or hallucinate functionality
- All documentation must be deterministic, explainable, and edition-aware
- Avoid repetition, boilerplate, or marketing fluff

Tone: Developer-facing. Clear. Focused. Helpful. Edition-aware. Cross-link capable.

Output only valid Markdown and JSON/YAML where applicable. Include `:::tip` blocks when summarizing suggestions or traceability.

You work closely with VisionArchitectAgent, QA Agent, Generator Agents, and Bug Resolver Agent.

🎯 Embedded Tone and Constraints¶

Rule	Description
🧾 Traceability enforced	Always include trace metadata block at top of document
📘 Consistent tone	Developer-friendly, informative, with minimal fluff
🔍 Memory-aware	Suggest links to prior features, modules, or diagrams
⚙️ Edition-safe	Include `editionId` and scope the content accordingly
📄 Markdown-first	Uses Markdown spec with enhancements (callouts, diagrams, tabs)

🧠 Roles Encoded in Prompt¶

Agent Behavior	Enabled
📄 Technical writer	Writes human-readable doc with headers, sections, links
🔗 Trace enhancer	Adds traceId, links to other memory entries, and related artifacts
🧠 Knowledge linker	Pulls relevant knowledge from memory when available
📦 Publisher	Emits docs for Studio previews, CI integration, or handoff to Developer Agents

✅ Sample System Prompt Use Case¶

When given:

traceId: proj-944
documentType: feature-blueprint
inputArtifact: trace.plan.yaml

The prompt instructs the agent to:

Generate feature-blueprint.md
Include trace block
Use MemoryLinkingSkill to reference other related capabilities
Emit studio.preview.json

✅ Summary¶

The System Prompt of the Documentation Write Agent guarantees that:

🧠 Content is memory-enriched and trace-linked
📄 Format adheres to ConnectSoft’s developer documentation standards
📤 Output is consistent, safe, and Studio-ready
🌍 Documentation is properly scoped by edition and module
🔗 Links and explanations are deterministic, explainable, and verifiable

This foundational prompt ensures the agent behaves as a professional AI doc writer embedded in a trace-first, clean architecture platform.

🧾 Input Prompt Template¶

This section defines the input prompt template used by the Documentation Write Agent to guide the LLM when composing Markdown content from structured inputs. It ensures that all outputs follow a predictable format, embed trace metadata, and reflect the intended document type.

📘 Input Prompt Template Structure¶

You are generating technical documentation based on the following structured artifact.

--- Document Type ---
{{documentType}}  # e.g. feature-blueprint, fix-report, test-plan, module-readme

--- Trace Metadata ---
traceId: {{traceId}}
agentId: {{agentId}}
editionId: {{editionId}}
moduleId: {{moduleId}}

--- Source Artifact ---
{{rawInput}}  # YAML, JSON, or extracted key-value structure

--- Guidelines ---
- Output must be valid Markdown
- Use H1 for title, H2/H3 for sections
- Include traceId and editionId visibly in the document
- If applicable, include Mermaid diagrams or `:::tip` blocks
- Do not hallucinate information not present in the input
- If the input is a fix, include patch summary and reasoning
- If the input is a test plan, list all test cases and coverage notes

📘 Example Input: Feature Blueprint¶

documentType: feature-blueprint
traceId: proj-811-v2
agentId: VisionArchitectAgent
editionId: vetclinic
moduleId: NotificationService

rawInput:
  featureId: notify-clients
  capabilities:
    - send confirmation email after booking
    - fallback to SMS
  involvedAgents:
    - ProductManagerAgent
    - MicroserviceGeneratorAgent

Resulting Output Prompt (injected to LLM):¶

You are generating technical documentation based on the following structured artifact.

--- Document Type ---
feature-blueprint

--- Trace Metadata ---
traceId: proj-811-v2
agentId: VisionArchitectAgent
editionId: vetclinic
moduleId: NotificationService

--- Source Artifact ---
featureId: notify-clients
capabilities:
  - send confirmation email after booking
  - fallback to SMS
involvedAgents:
  - ProductManagerAgent
  - MicroserviceGeneratorAgent

--- Guidelines ---
...

🧠 Semantic Parameters¶

Input Parameter	Use
`documentType`	Selects correct Markdown template
`rawInput`	Fills sections with structured YAML or JSON content
`traceId` / `editionId`	Rendered as part of trace metadata at the top
`agentId`	Used for authorship, attribution, or collaboration diagrams
`includeMemoryLinks` (optional)	Adds cross-links to prior docs or related fixes if available

🧩 Prompt Use Cases¶

Type	Behavior
`feature-blueprint`	Renders overview, capabilities, and related modules
`fix-report`	Embeds patch summary, root cause, and trace source
`test-plan`	Lists scenarios, modules tested, and expected coverage
`prompt-library`	Converts SK YAML prompts into a human-readable table or reference sheet
`module-readme`	Builds service readme with scope, dependencies, and diagram blocks

🔁 Format-Driven Prompt Injection¶

Used via Semantic Kernel with context:

context["documentType"] = "test-plan";
context["traceId"] = "proj-821-test-1";
context["editionId"] = "vetclinic-lite";
context["rawInput"] = yamlTestArtifact;

✅ Summary¶

The input prompt template enables the Documentation Write Agent to:

🧠 Compose structured documentation grounded in YAML/JSON inputs
📄 Inject traceability and authorship metadata
✍️ Write clear, deterministic, and edition-aware docs
🔗 Optionally link prior knowledge, diagrams, and test metadata
📦 Standardize content for review in Studio, CI, or human workflows

This ensures a clean, repeatable pipeline for autonomous documentation generation across ConnectSoft agents and editions.

📦 Output Format & Expectations¶

This section describes the expected output structure, formatting rules, and layout conventions for all documentation generated by the Documentation Write Agent. These outputs are traceable, edition-aware, Studio-compatible, and written in developer-friendly Markdown with enhanced features.

📄 Primary Output Format: Markdown (`.md`)¶

✅ Required Structure (Base Template)¶

# {{Document Title}}

> **Trace ID**: `{{traceId}}` | **Edition**: `{{editionId}}` | **Agent**: `{{agentId}}`

## Overview
{{One-paragraph summary of the document purpose}}

## Capabilities / Fix Summary / Scenario Listing
- Bullet points
- Test cases or features
- Key configuration or behaviors

## Details / Steps / Architecture
- Explanations
- Mermaid diagrams (if included)
- YAML blocks (if config specs involved)

:::tip
Cross-reference or guidance note related to trace or edition.
:::

## Related Artifacts
- [Link to source](...)
- [Feature plan](...)
- [Memory entry](...)

📘 Required Metadata (Embedded)¶

Metadata	Required?	Format
`traceId`	✅	Visible in top block
`editionId`	✅	Used to scope output path and section
`agentId`	✅	For attribution and Studio preview
`moduleId` (if applicable)	✅	For folder and content targeting
`fingerprintId` (for fixes)	Conditional	Added in `fix-report.md` or `studio.preview.json`

📦 Output Types and Expectations¶

Type	File	Output Rules
Feature Blueprint	`feature-blueprint.md`	One H1, trace block, capabilities list, linked modules
Fix Report	`fix-report.md`	Includes classification, fix strategy, explanation, diff links
Test Plan	`test-plan.md`	Lists `.feature` scenarios with scenario summaries and agent responsibilities
Module README	`README.md`	Contains architecture notes, usage, and edition badges
Studio Preview	`studio.preview.json`	Required for all docs; includes title, traceId, agent, edition, tags
Coverage Index	`documentation.index.yaml`	Tracks document type, location, trace, module, and status

🎨 Formatting Features¶

Feature	Markdown
Headings	`#`, `##`, `###` for H1–H3
Code blocks	```csharp ``` or YAML
Callouts	`:::tip`, `:::note`, `:::warning`
Mermaid	```graph TD```
Links	Relative markdown paths (e.g., `[Feature Doc](./feature-blueprint.md)`)
Tables	Markdown tables for prompt inputs, feature lists, etc.

🧾 Style & Tone Expectations¶

Rule	Description
✍️ Professional tone	Short, factual, helpful explanations — not marketing copy
🧠 Edition-aware	Call out if the doc applies only to `vetclinic-premium`, etc.
🔗 Trace-enriched	Links to artifacts using `traceId` and memory paths
📚 Modular	Prefer short documents per feature/module instead of giant monoliths
📎 Cross-linked	Reference related `.md`, `.yaml`, `.diff`, or `.feature` files with local paths

📘 Example: `studio.preview.json`¶

{
  "traceId": "proj-811-v2",
  "document": "feature-blueprint.md",
  "previewTitle": "Notify Clients After Booking",
  "editionId": "vetclinic",
  "tags": ["notification", "feature", "email", "SMS"],
  "agentId": "VisionArchitectAgent",
  "status": "documented"
}
````

---

### ✅ Summary

The Documentation Write Agent emits outputs that are:

* 📝 Written in **developer-grade Markdown** with trace-aware frontmatter
* 🔍 Structured, style-compliant, and enriched with **cross-links and visuals**
* 📊 Augmented by Studio preview files and documentation indexes
* 🔐 Scoped by `editionId` and `moduleId`, enabling modular delivery
* ✅ Conformant to the ConnectSoft documentation spec

This ensures **consistency, auditability, and usability** across the entire AI Software Factory documentation system.

---

## 🧠 Short-Term Memory

This section defines how the Documentation Write Agent uses **short-term memory (STM)** during execution to track active trace context, enrich documentation with local references, and preserve composition state across skill calls within a single generation session.

---

### 🧠 Purpose of Short-Term Memory

| Capability                    | Description                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------------- |
| 📍 Track trace metadata       | Holds `traceId`, `editionId`, `moduleId`, and `agentId` throughout the doc            |
| 📚 Maintain current doc state | Stores partial content, current section pointers, and injected components             |
| 🔄 Orchestrate skill output   | Transfers structured input → intermediate Markdown → final linted output              |
| 🔗 Hold local artifact map    | Temporarily caches related `.md`, `.yaml`, `.diff`, `.feature` file paths for linking |
| 🧩 Preserve enriched memory   | Stores summary blocks or knowledge retrieved for inline referencing during doc build  |

---

### 🧠 STM Example Snapshot

```json
{
  "traceId": "proj-811-v2",
  "editionId": "vetclinic",
  "agentId": "VisionArchitectAgent",
  "moduleId": "NotificationService",
  "documentType": "feature-blueprint",
  "currentTemplate": "feature-blueprint.md",
  "injectedSections": {
    "capabilities": ["send confirmation email", "fallback to SMS"],
    "agents": ["ProductManagerAgent", "MicroserviceGeneratorAgent"]
  },
  "linkedArtifacts": [
    "docs/features/notify-clients/fix-report.md",
    "docs/modules/NotificationService/README.md"
  ]
}

🔄 Skills That Use STM¶

Skill	How It Uses STM
`MarkdownComposerSkill`	Injects values from `currentTemplate`, `injectedSections`, and `trace metadata`
`MemoryLinkingSkill`	Uses `traceId` + `moduleId` to preload related docs or memory entries
`DocLinterSkill`	Accesses draft output in STM to validate structure and link consistency
`MermaidRendererSkill`	Tracks diagram reference paths injected into the document
`StudioPreviewGeneratorSkill`	Extracts summary and metadata from STM state for output preview file

⏳ Lifecycle of STM¶

Phase	Purpose
📥 On Input Load	Populates `traceId`, `rawInput`, and input type
🛠️ During Composition	Stores partial Markdown fragments and resolved links
🔍 During Enrichment	Caches memory snippets and diagrams for injection
📤 On Final Output	Used to populate preview, index, and trace overlays
🧼 On Completion	STM flushed and optionally written to logs for debugging or audit trail

🔐 Scope and TTL¶

Scope	Value
Trace-Scoped	Only persists within single `traceId` run
Agent-Isolated	Not shared across parallel doc generations
Expiry	Cleared after output written unless debug mode is enabled

🧠 Memory Fusion (Optional Advanced Behavior)¶

If multiple docs are being generated for a single trace run (e.g., feature-blueprint.md, test-plan.md, fix-report.md), the STM can be extended across runs via a trace composition session, enabling:

📘 Shared headers
🧩 Auto-linked doc sections
📂 Documentation index co-generation

✅ Summary¶

The Documentation Write Agent uses short-term memory to:

🧠 Track trace-linked metadata and document state
🧾 Compose, validate, and enrich content consistently across skills
🔗 Cross-link documents during generation
📤 Populate preview files and indexes post-generation

STM is a transient but critical component for ensuring every document is trace-aligned, well-structured, and enriched with meaningful local references.

🧠 Long-Term Memory¶

This section describes how the Documentation Write Agent interacts with long-term memory (LTM) — accessing previously generated documents, trace-linked knowledge, fix records, and prompt templates — to improve consistency, reusability, and cross-referencing in documentation.

📚 Role of Long-Term Memory¶

Function	Description
🔄 Retrieve past documentation	Enables linking to previously written documents for the same `traceId`, `moduleId`, or `editionId`
🧠 Use existing knowledge	Embeds summaries from `memory-entry.json`, `fix-history.yaml`, or `feature-blueprint.md`
📎 Maintain doc continuity	Reuses style, structure, and terminology already approved in prior related documents
💡 Inherit prompt snippets	Pulls documented prompts and response examples from previous `prompt-library.md`
📘 Inject reusable blocks	Imports intro sections, architecture diagrams, scenario lists, or changelogs from prior docs
📊 Enable coverage reporting	Tracks what has been documented vs. what remains via `documentation.index.yaml`

📂 Accessed Memory Sources¶

Artifact	Description
`memory-entry.json`	Traceable knowledge unit previously stored by another agent
`documentation.index.yaml`	Registry of docs by trace/module/edition, used for coverage and linking
`fix-report.md`	Summaries of previously applied fixes, used in architecture or changelog docs
`prompt-library.md`	Catalog of existing prompt formats and patterns
`feature-blueprint.md`	Primary reference for cross-linking feature → module → test → fix
`studio.preview.json`	Used for back-referencing docs from preview tiles or dashboards

📘 Example: Memory-Based Link Injection¶

Given:

current doc: test-plan.md for NotificationService
traceId: proj-888
memory-entry contains previous feature-blueprint.md

→ LTM enables:

## Related Features
- [Notify Clients After Booking](../features/notify-clients/feature-blueprint.md)

🧠 Knowledge Reuse Examples¶

Type	Use
🧾 Fix summary	Reused in root cause analysis sections of new documentation
🧠 Feature capabilities	Referenced in README or module index
📊 Diagram blocks	Injected into architecture or blueprint docs
📎 Prompt input/output examples	Embedded into `prompt-library.md` or instruction guides
✅ Validation outcomes	Used to show test success or bug regression fixes in QA documentation

🔐 Access Scope¶

Scope	Behavior
Edition-aware	Only memory linked to the same `editionId` is included unless explicitly overridden
Module-scoped	Searches for artifacts in the same service cluster (`NotificationService`, `Appointments`, etc.)
Trace-mapped	Prior documentation must share `traceId` lineage or be explicitly mapped via `trace-link-map.yaml`
Confidence-filtered	Memory entries below trust thresholds (e.g., unvalidated fix summaries) may be excluded from automatic injection

📊 Integration with Coverage Metrics¶

Pulls existing entries from documentation.index.yaml
Marks new docs as status: documented
Generates doc-coverage.metrics.json for dashboard tracking

✅ Summary¶

The Documentation Write Agent uses long-term memory to:

🧠 Leverage past documentation and trace knowledge
🔗 Create deep, trace-linked documents with historical awareness
♻️ Reuse patterns, terms, visuals, and validated outputs
📚 Maintain continuity across editions, modules, and features
📈 Enable coverage reporting, discovery, and enrichment

This allows the agent to act not just as a writer, but as a knowledge-aware documentation orchestrator within the ConnectSoft platform.

✅ Validation & Review¶

This section defines how the Documentation Write Agent ensures the quality, correctness, traceability, and completeness of all generated documentation through automated validation hooks, CI-integrated review signals, and Studio-facing previews.

✅ Validation Strategy Overview¶

Validation Stage	Description
🧾 Markdown structure check	Ensures correct use of headings (H1–H3), code blocks, and lists
🔗 Link checker	Validates that all relative links to `.md`, `.yaml`, `.diff`, `.feature` are resolvable
🧠 Trace metadata validation	Confirms `traceId`, `agentId`, `editionId` are present and match the document context
🔍 Lint ruleset	Applies ConnectSoft markdown rules: no empty headers, no unlinked references, callout formatting, edition labeling
📊 Preview integrity	Generates `studio.preview.json` and checks for correct keys, summary, and link to main document
📎 Cross-document coverage	Compares new doc against `documentation.index.yaml` and `trace-link-map.yaml` to confirm link completeness

📘 Example Lint Rules (enforced via `DocLinterSkill`)¶

Rule	Description
✅ Title is H1	Only one `#` heading per document
✅ Metadata block	Must include traceId, editionId visibly in top section
✅ No orphan headers	No `##` or `###` without content under it
✅ Inline YAML formatting	Must use fenced code blocks (```yaml) for structure
✅ Mermaid blocks valid	Mermaid syntax must parse (graph TD, flowchart, etc.)

🧪 Validation Outputs¶

File	Description
`doc-validation.log.jsonl`	Structured log of all passes, warnings, and failures (e.g., missing `traceId`, broken link)
`studio.preview.json`	Final preview data used by Studio; generation failure is treated as a documentation failure
`fix-validation-metadata.yaml`	If doc is based on a fix, links to validation test pass/fail data from QA Agent
`documentation.index.yaml` (updated)	Marked with `status: documented` and linked validation block if applicable

📎 Studio Review Integration¶

Feature	Description
✅ Preview block	Allows reviewers to open documentation, view metadata, and suggest edits
🟡 Status flags	Flags docs as `draft`, `needs-review`, `published`
✍️ Inline annotation	HumanOps and Developer Agents may annotate Markdown sections via Studio or PR UI
🔄 Re-generation trigger	On failed validation or manual rejection, prompt regeneration with preserved `traceId` and inputs

📊 CI/CD Integration¶

Job	Description
`lint-docs`	Verifies all `.md` and `.json` outputs conform to expected structure
`validate-links`	Runs link checker across generated docs and project folder
`verify-preview-json`	Ensures preview metadata matches doc name, tags, and edition scope
`publish-to-studio-preview`	Uploads docs for Studio tile rendering and visualization testing

✅ Summary¶

The Documentation Write Agent performs automated validation to ensure:

🧾 Structural and formatting correctness
🔗 Valid internal linking and trace path resolution
📊 Studio previews and CI/CD readiness
✍️ Optional human review support in Studio dashboard
📂 Indexing and edition-scoped trace coverage

This makes documentation auditable, reviewable, and deployment-ready as part of the ConnectSoft autonomous factory pipeline.

🔁 Retry and Correction Flow¶

This section explains how the Documentation Write Agent handles failures in content generation, formatting, validation, or trace integrity by triggering retries, fallback strategies, and optional correction workflows — either automatically or via manual agent/human-in-the-loop override.

🔁 Retry Triggers¶

Trigger	Description
❌ Validation failure	Linter detects structural issues, missing metadata, or broken links
⚠️ Missing section content	A required section (e.g., “Capabilities”) is empty after composition
🚫 Invalid Markdown syntax	Mermaid diagram parsing error, YAML block malformed, callout format broken
🔍 Link resolution failure	Document contains dead local or trace-relative links
🔎 Low content quality (auto-evaluated)	SK scoring below confidence threshold (e.g., poor summarization, under-filled tables)

🔁 Retry Flow Logic¶

flowchart TD
    Start[📝 Draft Composed]
    Lint[✅ Validate]
    Lint -->|Fail| RetryCheck[🔁 Retry Allowed?]
    RetryCheck -->|Yes| Retry[🛠️ Recompose Using Fallback]
    Retry --> Lint
    RetryCheck -->|No| Escalate[🧑‍💻 Flag for Review]

Hold "Alt" / "Option" to enable pan & zoom

🧩 Correction Strategies¶

Correction Type	Description
✍️ Template adjustment	If a required section fails, fallback template used (e.g., `feature-lite.md`)
🔁 Simplified summarization	Falls back to keyword-based summarizer if LLM fails to generate readable paragraph
📄 Memory trimming	Reduces memory block length if semantic overload or hallucination risk detected
🧠 Trace injection retry	Re-fetches trace context if `traceId` or `editionId` appears corrupted or mismatched
📎 Link validator override	Allows injection of temporary anchor if file is not yet generated but planned in the same session

📘 Retry Metadata (Stored in Log)¶

{
  "traceId": "proj-821",
  "documentType": "test-plan",
  "retryCount": 2,
  "lastFailureReason": "Missing scenario section",
  "strategyUsed": "Template fallback with callout injection"
}

🧑‍💻 Human-Aware Correction Path¶

Trigger	Outcome
🔎 Marked `needs-review` in Studio	Triggers regeneration option or manual Markdown edit
🛑 Exceeds 3 retries	Generates `doc-failure-report.yaml` for HumanOps Agent
✍️ Developer review rejection	Writes annotations to `studio.annotation.yaml`, regenerates with constraints

🔁 Retry Limits & Rules¶

Rule	Behavior
Retry attempts	Default: max 3 per document
Escalation	After 3 attempts, output marked as failed in `documentation.index.yaml`
Fallback allowed	Yes, for templates, summarizers, and injected metadata
Studio preview	Not emitted until successful validation + trace metadata presence

✅ Summary¶

The Documentation Write Agent includes a robust retry and correction loop to ensure that every document is:

🧠 Logically and structurally complete
✅ Formatted and validated successfully
🔁 Resilient to summarization or formatting failures
📘 Escalated or flagged with full trace metadata when human review is needed

This safeguards ConnectSoft’s commitment to high-quality, edition-aware, and production-grade documentation automation.

🤝 Collaboration Interfaces¶

This section details how the Documentation Write Agent collaborates with other ConnectSoft agents and systems — consuming their outputs, producing documentation for their artifacts, and synchronizing with shared trace, memory, and Studio tooling.

🔗 Upstream Agent Inputs¶

Agent	Provided Artifacts
VisionArchitectAgent	`trace.plan.yaml`, `feature-blueprint.input.yaml`
BugResolverAgent	`bug-resolution.yaml`, `fix-summary.md`
TestGeneratorAgent	`.feature` files, `test-results.json`
PromptArchitectAgent	`prompt.plan.yaml`, prompt YAML blocks
DeveloperAgent	`README.template.md`, `module.overview.yaml`
MicroserviceGeneratorAgent	`service.metadata.yaml`, `generated.api.yaml`
KnowledgeManagementAgent	`memory-entry.json`, `knowledge-index.yaml`, `trace-link-map.yaml`

📤 Outputs Consumed By¶

Agent	Artifact
StudioAgent	`studio.preview.json`, `.md` files for preview tiles and search
DeveloperAgent	`README.md`, `module-index.md`, and changelog summaries
KnowledgeManagementAgent	Final `.md`, `.yaml` docs stored as memory entries
QAEngineerAgent	`test-plan.md`, scenario explanations for regression coverage
HumanOpsAgent	`doc-validation.log.jsonl`, `studio.annotation.yaml`, and retry/escalation logs
PromptArchitectAgent	`prompt-library.md`, `instruction.md` for prompt introspection and reusability

📘 Collaboration Flow Diagram¶

flowchart TD
    VISION[Vision Architect Agent]
    TEST[Test Generator Agent]
    BUG[Bug Resolver Agent]
    DEV[Developer Agent]
    PROMPT[Prompt Architect Agent]
    DOC[📝 Documentation Write Agent]
    KM[Knowledge Management Agent]
    STUDIO[Studio Agent]

    VISION --> DOC
    TEST --> DOC
    BUG --> DOC
    DEV --> DOC
    PROMPT --> DOC
    DOC --> KM
    DOC --> STUDIO
    DOC --> DEV

Hold "Alt" / "Option" to enable pan & zoom

🧠 Shared Interfaces¶

Interface	Type	Description
`traceId`, `artifactId`	Metadata	Enables cross-agent traceability
`memory-entry.json`	Knowledge API	Used for enriching docs and linking past resolutions
`studio.preview.json`	Dashboard Preview	Allows Studio Agent to generate preview tiles and metrics
`documentation.index.yaml`	Registry	Shared index of all docs generated per project or edition
`doc-coverage.metrics.json`	Metrics	Tracks which modules or features are documented or not

🤖 Agent Collaboration Use Cases¶

Scenario	Behavior
🛠 Bug fixed → doc generated	Bug Resolver Agent emits patch → DOC Agent writes `fix-report.md`
🧪 Test generated → doc explained	Test Generator emits `.feature` → DOC Agent creates `test-plan.md`
📦 Service generated → doc emitted	Microservice Generator builds `CatalogService` → DOC Agent writes `README.md`
✍️ Prompt defined → instruction guide written	Prompt Architect Agent emits prompt → DOC Agent creates `prompt-library.md`

✍️ Human-Review Interfaces (via Studio)¶

Integration	Function
Preview tile	Show rendered `.md` content and preview metadata
Status flags	Indicates `documented`, `needs-review`, `published`
Studio annotation hooks	Allows human reviewers to add comments or suggest regeneration
Markdown diff viewer	Compares agent-generated output to previous versions for approval or rollback

✅ Summary¶

The Documentation Write Agent collaborates across the ConnectSoft platform by:

📥 Consuming structured outputs from planning, testing, development, and fix agents
🧾 Producing documentation that is used by QA, Dev, Studio, and Memory agents
🔗 Ensuring every doc is trace-linked and preview-ready for Studio dashboards
🤝 Supporting both autonomous and human-in-the-loop documentation workflows

This makes the agent the hub of AI-generated traceable knowledge, central to ConnectSoft’s vision of autonomous, explainable SaaS development.

📊 Observability Hooks¶

This section describes how the Documentation Write Agent integrates with ConnectSoft’s observability infrastructure to track activity, performance, document coverage, generation health, and output quality — across CI/CD, Studio, and agent workflows.

📡 Telemetry Events Emitted¶

Event Name	Triggered When	Payload Includes
`DocGenerationStarted`	Document generation initiated	`traceId`, `documentType`, `agentId`, `editionId`
`DocGeneratedSuccessfully`	Document emitted and validated	`outputPath`, `traceId`, `documentType`, `durationMs`
`DocValidationFailed`	Lint, metadata, or structure error occurs	`reason`, `lineNumber`, `section`, `traceId`
`PreviewPublished`	`studio.preview.json` successfully created	`previewTitle`, `tags`, `status`, `traceId`
`DocCoverageUpdated`	Documentation index or metrics regenerated	`moduleId`, `status`, `documentTypes`, `totalDocs`

All events are logged via OpenTelemetry and optionally piped into Application Insights, Studio dashboards, or build telemetry collectors.

📘 Log Artifacts Generated¶

File	Description
`doc-validation.log.jsonl`	Structured logs for each generated file (warnings, errors, retry history)
`studio.preview.json`	Used to update preview tiles and metadata in Studio
`documentation.index.yaml`	Index of all documentation files by trace, edition, module, type
`doc-coverage.metrics.json`	Coverage report: counts, editions covered, doc types emitted, etc.
`doc-generation.trace.json`	Full trace path for debugging issues across skills and retries

📊 Key Metrics Tracked¶

Metric	Purpose
`docCountPerEdition`	Documents emitted by `editionId`
`coverageByCluster`	Tracks how many features, services, or modules are documented in each agent cluster (QA, Architecture, etc.)
`avgGenerationTimeMs`	Per document type or artifact size
`retryRateByTemplate`	Tracks how often fallback templates are used
`studioPreviewSuccessRate`	Detects mismatches between doc emission and preview publication
`validationFailureRate`	Segment by cause: broken link, lint error, missing metadata, etc.

📎 Studio Observability Integration¶

Feature	Description
🔍 Documentation search	Indexes titles, traceIds, and tags from `studio.preview.json`
📦 Tile metrics	Number of documented modules, features, bugs, tests — shown as status bars
📎 Live preview panel	Uses latest Markdown to render an inline preview
📘 Diff viewer	Supports Markdown version comparison and rollback audit trails
✅ Status labels	`draft`, `needs-review`, `validated`, `published` derived from doc state machine

🚦 CI/CD Observability Hooks¶

Hook	Function
`validate-docs`	Runs linting, formatting, and trace validation during pipeline build
`publish-preview`	Uploads Studio preview and pushes `DocGeneratedSuccessfully` event
`generate-index`	Updates documentation index and coverage metrics YAML files
`publish-telemetry`	Sends OpenTelemetry span logs for dashboards or alerts (optional)

📁 Traceability Tags in Logs¶

Every telemetry output includes:

traceId
agentId
editionId
documentType
outputFilePath
retryCount (if any)
timestamp (ISO-8601)

✅ Summary¶

The Documentation Write Agent includes full observability instrumentation to ensure:

📊 Live insights into documentation health, coverage, and validation
🧾 Auditability for every document generated, retried, or escalated
✅ Feedback loops into Studio dashboards and CI/CD pipelines
🔍 Root cause tracking for generation or formatting failures

This ensures that documentation is as observable as code or infrastructure, in alignment with ConnectSoft’s observability-first architecture.

🧑‍💻 Human Intervention Hooks¶

This section defines how human reviewers — including technical writers, developers, and project leads — can interact with, review, override, and improve the outputs of the Documentation Write Agent. It supports a hybrid workflow of autonomous generation with manual checkpoints and collaboration.

✍️ When Human Intervention Is Allowed or Triggered¶

Scenario	Trigger
🟡 `needs-review` flag applied	Low confidence generation score or partial section failure
❌ Validation failures	After 3 failed retries (structure, link, or content issues)
📤 Manual annotation provided	HumanOps or Developer Agent leaves suggestions in Studio
🧠 Critical doc type or audit trace	Company policy enforces human approval before publishing (e.g., security overview, client-facing SDK README)
🔄 Prompt evolution in progress	PromptArchitectAgent or VisionArchitectAgent requests review during generation of prompt-based or strategy-based content

👩‍💻 Human Interaction Points (Studio + Git)¶

Interface	Feature
Studio Preview Tile	View live doc preview rendered from `.md`
Inline Review UI	Leave comments on specific lines or sections
Annotation Panel	Add global feedback (e.g., “Add architecture diagram”)
Status Buttons	Approve, Reject, Regenerate with constraints
Diff Comparison View	Compare regenerated vs. prior version side-by-side
Override with Manual Edits	Accept hand-edited `.md` file and flag as `human-curated` in index

📎 Review Metadata (Stored in `studio.annotation.yaml`)¶

traceId: proj-899
document: feature-blueprint.md
reviewedBy: daniel.mizrahi@connectsoft.ai
status: needs-revision
comments:
  - section: Capabilities
    message: "Please clarify the fallback mechanism for SMS failure"
  - section: Overview
    message: "Add Mermaid diagram for the notification flow"
timestamp: 2025-05-15T22:55:00Z

🔁 Supported Human Actions¶

Action	Effect
✅ Approve	Marks doc as `validated` and updates index + Studio tile
📝 Annotate	Adds in `studio.annotation.yaml`, triggers conditional regeneration
🛑 Reject	Writes failure note and flags doc for escalation or human rewrite
🛠️ Override + Save	Developer provides manually corrected `.md` file; future agents can learn from this
🔁 Constrain Retry	Reviewer specifies which section or macro to retry (e.g., regenerate "Test Scenarios" only)

📘 Escalation Paths¶

Condition	Behavior
Review not completed in time	Triggers reminder or fallback to retry after cooldown window
Critical doc required	If marked `blocking: true` in `trace.plan.yaml`, must be reviewed before doc is marked as published
Studio status = `needs-human`	Appears in review backlog dashboard for prioritization

🧾 Audit and Coverage Logs¶

Artifact	Description
`studio.annotation.yaml`	Full record of human feedback, linked to traceId and doc path
`documentation.index.yaml`	Flags documents as `human-reviewed`, `machine-generated`, or `override-applied`
`doc-review-history.jsonl`	Append-only log of all human feedback across docs, reviewers, and trace groups

✅ Summary¶

The Documentation Write Agent integrates with human intervention workflows to support:

✅ Structured review of sensitive or critical documentation
🧾 Feedback loops that improve future generation quality
🔍 Studio dashboard visibility of what needs review or approval
🛠️ Manual override paths for high-trust outputs (e.g., SDKs, policies)
📎 Proper annotation, audit logging, and trace alignment

This balances autonomy with oversight, ensuring ConnectSoft documentation is trustworthy, collaborative, and production-safe.

🧾 Summary and Positioning¶

This final section consolidates the agent’s responsibilities, integration, skills, and system role — demonstrating how the Documentation Write Agent acts as the voice of the AI Software Factory, transforming structured artifacts into production-grade, traceable, and edition-aware documentation.

🎯 Core Purpose Recap¶

The Documentation Write Agent turns structured outputs from ConnectSoft agents into Markdown-based, trace-linked, human- and agent-readable documentation — with Studio previews, trace metadata, validation, and observability.

🧩 Position in the ConnectSoft Platform¶

flowchart TD
    PLAN[📊 Planning Agents]
    DEV[🛠 Developer Agents]
    TEST[🧪 QA/Test Agents]
    FIX[🐞 Bug Resolution Agents]
    PROMPT[🧠 Prompt Architect Agents]
    DOC[📝 Documentation Write Agent]
    STUDIO[📊 Studio Agent]
    KM[🧠 Knowledge Management Agent]

    PLAN --> DOC
    DEV --> DOC
    TEST --> DOC
    FIX --> DOC
    PROMPT --> DOC
    DOC --> STUDIO
    DOC --> KM

Hold "Alt" / "Option" to enable pan & zoom

🧠 Responsibilities Overview¶

Responsibility	Output
📄 Compose documents from artifacts	`README.md`, `fix-report.md`, `feature-blueprint.md`, `test-plan.md`
🧾 Format and validate	Linted, structured, and edition-aware `.md`, `.yaml`, `.json`
🔗 Link across memory and trace	Injects memory summaries and related artifact links
📊 Emit previews and metrics	`studio.preview.json`, `doc-coverage.metrics.json`, `documentation.index.yaml`
🧑‍💻 Support human review	Studio-based review, annotation, and manual overrides

⚙️ Skills & Technology¶

Layer	Tools
🧠 Semantic Kernel	Markdown composition, prompt injection, skill chaining
📦 Azure OpenAI	Summarization, section formatting, tone enforcement
📊 Observability	OpenTelemetry, Application Insights, Studio dashboards
🧰 Output Formats	Markdown, Mermaid, JSON, YAML
🧠 Memory	`memory-entry.json`, `knowledge-index.yaml`, trace maps

📘 Outputs Produced¶

Type	File
Technical Documentation	`*.md` (human-readable)
Studio Metadata	`studio.preview.json`
Coverage & Index	`documentation.index.yaml`, `doc-coverage.metrics.json`
Validation Logs	`doc-validation.log.jsonl`, `studio.annotation.yaml`

🧩 Collaboration Role¶

🧠 Consumes: Planning, Fix, Test, Prompt, and Developer agent outputs
📤 Produces: Documents and previews for Studio, CI, QA, KM, and DevOps
🔄 Feeds: Memory graph, prompt library, changelog systems, and agent knowledge modules

✅ Summary¶

The Documentation Write Agent:

🧾 Generates traceable, edition-aware, explainable documentation
📄 Turns raw trace artifacts into fully structured .md, .yaml, and .json files
🔗 Cross-links memory, bug reports, tests, features, and modules
🧠 Leverages Semantic Kernel + long-term memory + Studio integration
📊 Enables observability, audit, and governance for every document
🤝 Supports both autonomous and human-in-the-loop content generation

🏁 Final Positioning¶

The Documentation Write Agent is:

📘 The narrative layer of the ConnectSoft AI Software Factory — turning multi-agent outputs into cohesive, validated, and Studio-ready documentation that powers traceability, developer experience, and autonomous lifecycle transparency.

📝 Documentation Write Agent Specification¶

📌 Purpose¶

🎯 Primary Goals¶

🧩 Key Use Cases¶

📘 Typical Output Types¶

🧠 Agent Class & Personality¶

🧭 System Role¶

✅ Summary¶

📋 Responsibilities¶

✅ Core Responsibilities¶

🧾 Supported Artifact Types¶

🛠️ Post-Processing Duties¶

🧩 Role in Documentation Lifecycle¶

✅ Summary¶

📥 Inputs Consumed¶

📂 Primary Input Artifacts¶

📘 Example: trace.plan.yaml¶

📘 Example: bug-resolution.yaml¶

🔄 Dynamic Inputs (via Skill Context or Vector Search)¶

🧠 Semantic Kernel Input Context¶

📎 Inputs from Studio Agent¶

✅ Summary¶

📤 Outputs Produced¶

📄 Markdown Documentation Outputs¶

🧾 YAML / JSON Metadata Outputs¶

📘 Example: README.md (Microservice)¶

📘 Example: fix-report.md¶

📎 Studio Preview Output Example (studio.preview.json)¶

🧠 Cross-Linked Output¶

✅ Summary¶

🧠 Knowledge Base¶

📚 Pretrained & Embedded Knowledge¶

📁 Examples of Internal Templates¶

✅ feature-blueprint.md Template¶

✅ fix-report.md Template¶

🧠 Pattern-Matching Capabilities¶

🔁 Memory-Aware Composition¶

📘 Example:¶

🧾 Prebuilt Markdown Components¶

✅ Summary¶

🔄 Process Flow (High-Level)¶

📊 High-Level Flow Diagram¶

🧩 Phases Overview¶

1. 📥 Input Received¶

2. 🧠 Retrieve Context¶

3. 📄 Select Template¶

4. 📝 Generate Content¶

5. 🔗 Enrich Output¶

6. ✅ Validate¶

7. 📤 Emit Output¶

📘 Example Trigger Flow: Feature Plan¶

✅ Summary¶

🔬 Process Flow (Detailed)¶

🔁 Detailed Workflow Steps¶

🧩 Detailed Step Breakdown¶

1. 📥 Input Artifact Received¶

2. 🧠 Retrieve Trace Context¶

3. 🔍 Memory Query (Optional)¶

4. 📄 Template Selection¶

5. 🧠 Compose Draft¶

6. 🔗 Enrich Draft¶

7. ✅ Validate Output¶

8. 📤 Emit Final Artifacts¶

✅ Example: Test Plan Generation¶

✅ Summary¶

🧩 Skills & Kernel Functions Used¶

🧠 Core Semantic Kernel Skills¶

📘 Example: MarkdownComposerSkill¶

🔁 Cross-Skill Orchestration Example¶

🧩 Utility Functions¶

📎 Exposed for Other Agents¶

✅ Summary¶

🛠️ Technology Stack¶

💻 Core Stack¶

🧠 Memory and Trace Infrastructure¶

📘 Output File Types¶

🧰 Markdown Tooling¶

🛡️ Clean Architecture Enforcement¶

📡 Observability and CI/CD Integration¶

🔁 Reusability Across Agents¶

📘 Example: `trace.plan.yaml`¶

📘 Example: `bug-resolution.yaml`¶

📘 Example: `README.md` (Microservice)¶

📘 Example: `fix-report.md`¶

📎 Studio Preview Output Example (`studio.preview.json`)¶

✅ `feature-blueprint.md` Template¶

✅ `fix-report.md` Template¶

📘 Example: `MarkdownComposerSkill`¶

📄 Primary Output Format: Markdown (`.md`)¶

📘 Example: `studio.preview.json`¶

📘 Example Lint Rules (enforced via `DocLinterSkill`)¶