AI Documentation Workflow

Overview

This guide establishes the proper workflow for using AI assistants to create and maintain documentation while ensuring consistency with our system rules and preventing contradictions.

Critical Requirement: All AI-generated documentation must follow this workflow to prevent architectural contradictions and maintain single-author consistency across the project.

Pre-Documentation Checklist

Before asking AI to write or modify ANY documentation:

Step 1: Identify Authoritative Sources

Always identify and reference the authoritative source for the topic:

□ Check the Feature Implementation Decision Tree first
□ Verify current implementation examples in codebase
□ Identify any existing documentation on the topic
□ Note any system rules that apply

Primary Sources (in order of authority):

Feature Implementation Decision Tree - Authoritative for all placement decisions
Existing implementations - Actual code in the codebase
AI Coding Standards - Single author consistency rules
Documentation Guidelines - Structure and format rules

Step 2: Search for Existing Patterns

□ Search codebase for similar implementations
□ Check multiple component examples for consistency
□ Verify patterns match the decision tree guidance
□ Look for any conflicting guidance in existing docs

Required Search Commands:

# Search for existing component structures
find ui/foundation -name "types.ts" -type f
 
# Search for existing pattern examples  
grep -r "interface.*Props" ui/
 
# Check for contradictory guidance
grep -r "ButtonProps" content/docs/

Step 3: Verify No Contradictions Exist

□ Cross-reference multiple documentation sources
□ Check if guidance matches actual implementations
□ Identify any outdated or conflicting information
□ Note discrepancies for correction

If contradictions are found, STOP and resolve them before proceeding.

Proper AI Prompting Format

❌ WRONG Prompting

"Document how to create component types"
"Write documentation about ButtonProps"
"Create a guide for type organization"

✅ CORRECT Prompting

"Based on the Feature Implementation Decision Tree at /docs/guides/feature-implementation-decision-tree, 
I need to document component type placement. I've verified that:

1. Foundation components use co-located types (confirmed in ui/foundation/Button/types.ts)
2. The decision tree shows types.ts files within component directories
3. All examples follow this pattern consistently

Please follow:
- @ai-coding-standards for single author consistency
- @technical-documentation-guidelines for structure
- @documentation-writing-best-practices for DRY principle

Reference the decision tree as the authoritative source and ensure all examples align with it."

Required AI Response Format

AI responses MUST start with verification:

"Based on the Feature Implementation Decision Tree, component types belong in [exact location]..."
"I found consistent patterns in [specific files] that confirm this approach..."
"This aligns with the authoritative guidance in [reference document]..."

Documentation Verification Process

After AI generates documentation:

Step 1: Verify Accuracy

□ Does the guidance match the Feature Implementation Decision Tree?
□ Are the examples consistent with existing implementations?
□ Does it reference the correct authoritative sources?
□ Are file paths accurate per the actual project structure?

Step 2: Check for Contradictions

□ Search for conflicting guidance in other docs
□ Verify examples match the recommended patterns
□ Ensure no outdated information is referenced
□ Check that terminology is consistent project-wide

Step 3: Cross-Reference Links

□ Do all internal links point to correct documents?
□ Are cross-references accurate and helpful?
□ Is the documentation following DRY principle?
□ Are we referencing the single source of truth?

Preventing Common Mistakes

Mistake 1: Ignoring the Decision Tree

Problem: Writing placement guidance without consulting the Feature Implementation Decision Tree.

Solution: Always reference the decision tree first and use it as the authoritative source.

Example Prevention:

// ❌ WRONG
Place ButtonProps in core/shared/types/ for reusability.
 
// ✅ CORRECT  
Per the [Feature Implementation Decision Tree](/docs/guides/feature-implementation-decision-tree), 
ButtonProps belongs in ui/foundation/Button/types.ts as foundation components use co-located types.

Mistake 2: Creating Contradictory Examples

Problem: Showing examples that contradict established patterns.

Solution: Always verify examples against actual implementations.

Example Prevention:

// ❌ WRONG - Shows ButtonProps in shared types
// core/shared/types/ui.ts
export interface ButtonProps { ... }
 
// ✅ CORRECT - Shows actual pattern from codebase
// ui/foundation/Button/types.ts
export interface ButtonProps { ... }

Mistake 3: Missing Cross-References

Problem: Not linking to authoritative sources.

Solution: Always reference the decision tree and related documentation.

Example Prevention:

// ❌ WRONG
Component types should be co-located.
 
// ✅ CORRECT
Component types should be co-located with their components, as specified in the 
[Feature Implementation Decision Tree](/docs/guides/feature-implementation-decision-tree).

Quality Assurance Checklist

Before publishing any AI-generated documentation:

Content Accuracy

All file paths exist and are correct
Examples match actual implementations
Guidance aligns with authoritative sources
No contradictory information introduced

Consistency

Terminology matches project standards
Format follows documentation guidelines
Cross-references are accurate and helpful
Tone matches existing documentation

Architectural Alignment

Placement decisions reference decision tree
Examples follow established patterns
Import paths are accurate
Component organization follows three-layer architecture

Update Workflow for Contradictions

When contradictions are discovered:

Step 1: Identify Root Source

□ Find the authoritative source (usually decision tree)
□ Identify all contradictory documentation
□ List specific files that need updating
□ Verify the correct pattern in actual code

Step 2: Plan Updates

□ Update contradictory files to match authoritative source
□ Add cross-references to prevent future contradictions
□ Include clarifying notes about common misconceptions
□ Update any related examples or patterns

Step 3: Apply Changes

□ Update all conflicting documentation
□ Add proper cross-references
□ Verify consistency across all updated files
□ Test that all links still work

Success Criteria

Documentation following this workflow will achieve:

✅ Consistency: All guidance aligns with authoritative sources ✅ Accuracy: Examples match actual implementations ✅ Maintainability: Single source of truth prevents drift ✅ Usability: Clear, non-contradictory guidance for developers

Tools and Commands

Essential Search Commands

# Find component type patterns
find ui/ -name "types.ts" -exec grep -l "interface.*Props" {} \;
 
# Search for contradictory guidance
grep -r "ButtonProps" content/docs/ | grep -v "ui/foundation"
 
# Verify file paths in documentation
grep -r "ui/foundation/Button" content/docs/

Verification Scripts

# Check for common contradictions
./scripts/check-documentation-consistency.sh
 
# Verify all internal links work
./scripts/verify-doc-links.sh
 
# Validate examples against actual code
./scripts/validate-doc-examples.sh

Feature Implementation Decision Tree - Primary reference for all placement decisions
AI Coding Standards - Single author consistency requirements
Documentation Writing Best Practices - DRY principle and cross-referencing
Technical Documentation Guidelines - Structure and format requirements

Remember: The Feature Implementation Decision Tree is the authoritative source for all architectural decisions. When in doubt, reference it first and ensure all documentation aligns with its guidance.

AI Documentation Workflow

Overview

Pre-Documentation Checklist

Step 1: Identify Authoritative Sources

Step 2: Search for Existing Patterns

Step 3: Verify No Contradictions Exist

Proper AI Prompting Format

❌ WRONG Prompting

✅ CORRECT Prompting

Required AI Response Format

Documentation Verification Process

Step 1: Verify Accuracy

Step 2: Check for Contradictions

Step 3: Cross-Reference Links

Preventing Common Mistakes

Mistake 1: Ignoring the Decision Tree

Mistake 2: Creating Contradictory Examples

Mistake 3: Missing Cross-References

Quality Assurance Checklist

Content Accuracy

Consistency

Architectural Alignment

Update Workflow for Contradictions

Step 1: Identify Root Source

Step 2: Plan Updates

Step 3: Apply Changes

Success Criteria

Tools and Commands

Essential Search Commands

Verification Scripts

AI Documentation Workflow

On this page