Tool Context Documentation System

Overview

The Tool Context Documentation System preserves valuable execution results, decisions, and learnings from tool runs as persistent markdown documents. These documents can be referenced in future sessions to maintain consistency, avoid re-work, and provide context across long-running projects.

Purpose

When tools like bootstrap_validation_loop, deployment_readiness, or perform_research run, they generate valuable context including:

Platform detection results
Validated patterns and deployment strategies
Environment-specific configurations
Research findings and cached results
Architectural decisions and their rationale
Execution learnings (successes, failures, recommendations)

Without persistent context documents, this information is lost after the session ends, forcing developers and AI assistants to:

Re-discover platform and environment details
Re-research the same questions
Risk inconsistent decisions across sessions
Lose valuable learnings from previous executions

How It Works

Context Document Generation

Tools automatically generate context documents during execution using the ToolContextManager utility. Each document follows a standardized structure:

# Tool Context: {Tool Name}

> **Generated**: {ISO timestamp}
> **Tool Version**: {version}
> **Project**: {project name}

## Quick Reference

Brief summary for immediate use

## Execution Summary

- Status, confidence, key findings

## Detected Context

Platform, environment, technology details

## Generated Artifacts

Files, ADRs, configs created

## Key Decisions

Architectural and deployment decisions

## Learnings & Recommendations

Successes, failures, recommendations

## Usage in Future Sessions

How to reference this context

Storage Structure

Context documents are organized by category in docs/context/:

docs/context/
├── README.md (this file)
├── bootstrap/
│   ├── latest.md                          # Always points to most recent
│   ├── bootstrap-validation-2025-01-19.md # Timestamped execution
│   └── bootstrap-validation-2025-01-15.md # Historical context
├── deployment/
│   ├── latest.md
│   └── readiness-check-2025-01-19.md
├── environment/
│   ├── latest.md
│   └── analysis-2025-01-18.md
├── research/
│   ├── latest.md
│   ├── openshift-patterns-2025-01-19.md
│   └── kubernetes-research-2025-01-17.md
├── planning/
│   ├── latest.md
│   └── architecture-session-2025-01-16.md
└── validation/
    ├── latest.md
    └── adr-validation-2025-01-18.md

Category	Description	Example Tools
`bootstrap`	Platform detection, validated patterns, deployment plans	bootstrap_validation_loop
`deployment`	Deployment readiness, analysis, execution results	deployment_readiness, deployment_analysis
`environment`	Environment configuration, tool detection, capabilities	environment_analysis
`research`	Research findings, cached results, technology decisions	perform_research, research_integration
`planning`	Planning sessions, architectural options, trade-offs	interactive_adr_planning
`validation`	Validation results, compliance checks, quality scores	adr_validation
`git`	Git workflow patterns, commit conventions, branch strategies	smart_git_push

Usage Patterns

Pattern 1: Starting a New Session with Context

Without Context:

User: "Continue the OpenShift deployment"
AI: "Let me detect your platform and analyze your project..."
[Re-runs detection, re-researches, loses previous decisions]

With Context:

User: "Using the context from docs/context/bootstrap/latest.md,
continue the OpenShift deployment"

AI: [Reads context]
"I see from the bootstrap context that:
- Platform: OpenShift (95% confidence)
- Validated pattern: Multicluster GitOps v2.0
- Bootstrap ADR: docs/adrs/bootstrap-deployment-1234.md
- Last execution: Phase 2 complete, Phase 3 pending

Continuing with Phase 3: Deployment Validation..."

Pattern 2: Referencing Context in Prompts

For AI Assistants:

"Before generating the deployment plan, read the bootstrap context
from docs/context/bootstrap/latest.md to understand the detected
platform and validated pattern."

For Developers:

# Check what was previously detected
cat docs/context/bootstrap/latest.md

# Find specific research results
grep -r "Firebase" docs/context/research/

# Compare current vs previous deployment
diff docs/context/deployment/latest.md \
     docs/context/deployment/readiness-check-2025-01-15.md

Pattern 3: Onboarding New Team Members

New developers can quickly understand project-specific patterns:

Read docs/context/README.md - Understanding the context system
Read docs/context/bootstrap/latest.md - Current deployment approach
Read docs/context/environment/latest.md - Environment setup
Read relevant ADRs linked in context docs

Pattern 4: CI/CD Pipeline Consistency

CI/CD pipelines can reference context for consistent deployments:

# .github/workflows/deploy.yml
- name: Use Bootstrap Context
  run: |
    echo "Using context from docs/context/bootstrap/latest.md"
    # Extract deployment configuration from context

- name: Deploy
  run: ./bootstrap.sh

Referencing Context Documents

In AI Prompts

Claude / GPT-4:

System instructions or prompt:
"When working on deployment tasks, always check:
1. docs/context/bootstrap/latest.md - Platform and deployment context
2. docs/context/environment/latest.md - Environment configuration
3. docs/context/research/latest.md - Research findings

Use this context to inform decisions and maintain consistency."

Gemini (limited context window):

"Before answering, read these context documents:
- docs/context/bootstrap/latest.md
- docs/context/environment/latest.md

Then proceed with the task using the information from these documents."

In Code and Scripts

import { ToolContextManager } from './utils/context-document-manager';

const contextManager = new ToolContextManager(projectPath);

// Load latest bootstrap context
const contexts = await contextManager.listContexts('bootstrap');
const latestContext = contexts[0]; // Most recent

// Reference in decision-making
console.log(`Using platform from context: ${latestContext}`);

Retention Policy

latest.md: Always points to the most recent context for that category
Historical: Last 10 executions per category are kept by default
Archive: Older contexts can be moved to archive/ subdirectory
Cleanup: Use cleanupOldContexts() method to prune old contexts

// Clean up old contexts, keeping last 10
await contextManager.cleanupOldContexts('bootstrap', 10);

Benefits

For Developers

✅ Faster onboarding - Context docs provide project-specific knowledge
✅ Consistent decisions - Reference previous validated patterns
✅ Reduced re-work - Avoid re-discovering platform, environment, configs
✅ Better troubleshooting - Historical context for debugging
✅ Knowledge preservation - Decisions and learnings persist beyond individual sessions

For AI Assistants

✅ Context preservation - Overcome limited context windows
✅ Decision consistency - Maintain architectural alignment across sessions
✅ Reduced hallucination - Ground decisions in documented context
✅ Faster execution - Skip re-analysis, use cached research
✅ Continuity - Pick up exactly where previous session left off

For Teams

✅ Knowledge sharing - Context docs are team knowledge base
✅ Audit trail - Historical decisions and their rationale
✅ Compliance - Document deployment decisions for governance
✅ Collaboration - Shared understanding of project state

Examples

Bootstrap Context Example

See a complete example in the design document: docs/how-to-guides/tool-context-documentation-plan.md

A typical bootstrap context document includes:

Detected platform (OpenShift, Kubernetes, Docker, etc.)
Validated pattern selection (Multicluster GitOps, etc.)
Authoritative sources consulted
Deployment plan with required files and steps
Environment configuration
Generated artifacts (ADRs, scripts)
Key decisions and their rationale

Research Context Example

Research context documents capture:

Research question asked
Sources consulted (documentation, GitHub, Stack Overflow)
Research findings with confidence scores
Technology decisions based on research
Cached results for future reference

Best Practices

Always check for existing context before starting analysis or research
Reference context in prompts to maintain consistency
Update context after significant changes to keep it current
Link related contexts in the relatedDocuments section
Use descriptive quick references for easy scanning
Include confidence scores for transparency
Document learnings - both successes and failures
Keep rawData optional - only include when needed for debugging

Tools That Generate Context

Tool	Context Category	Generated Document
bootstrap_validation_loop	bootstrap	Platform detection, validated patterns, deployment plans
deployment_readiness	deployment	Readiness assessment, blockers, compliance checks
deployment_analysis	deployment	Current state analysis, optimizations
environment_analysis	environment	Environment config, tools, capabilities
perform_research	research	Research findings, cached results, decisions
interactive_adr_planning	planning	Planning decisions, options considered, trade-offs
adr_validation	validation	Validation results, quality scores, recommendations
smart_git_push	git	Git workflow patterns, conventions, push validation

Troubleshooting

Context document not found

# List all contexts in a category
ls -la docs/context/bootstrap/

# Check if category directory exists
ls -la docs/context/

Context is outdated

# View all contexts sorted by date
ls -lt docs/context/bootstrap/

# Compare with current project state
cat docs/context/bootstrap/latest.md

Too many old contexts

# Clean up old contexts (manual)
cd docs/context/bootstrap
ls -t | tail -n +11 | xargs rm

# Or use the cleanup method in code
await contextManager.cleanupOldContexts('bootstrap', 10);

Future Enhancements

Planned Features (v2.0)

Semantic search across all context documents
Context diff tool for visual comparison
Context validation to ensure docs match current project state
Auto-expiration based on relevance, not just age

Future Vision (v3.0)

Context graph showing relationships between contexts, ADRs, and code
AI-powered summarization of context documents
Context recommendations suggesting relevant docs for current task
Cross-project context sharing validated patterns across multiple projects

Contributing

To add context generation to a new tool:

Import ToolContextManager
Create context document after tool execution
Save to appropriate category
Return context path in tool results
Document in this README

See the implementation plan in docs/how-to-guides/tool-context-documentation-plan.md for detailed guidance.

Need help? See the Tool Context Documentation Plan for complete implementation details.

Overview​

Purpose​

How It Works​

Context Document Generation​

Storage Structure​

Categories​

Usage Patterns​

Pattern 1: Starting a New Session with Context​

Pattern 2: Referencing Context in Prompts​

Pattern 3: Onboarding New Team Members​

Pattern 4: CI/CD Pipeline Consistency​

Referencing Context Documents​

In AI Prompts​

In Code and Scripts​

Retention Policy​

Benefits​

For Developers​

For AI Assistants​

For Teams​

Examples​

Bootstrap Context Example​

Research Context Example​

Best Practices​

Tools That Generate Context​

Troubleshooting​

Context document not found​

Context is outdated​

Too many old contexts​

Future Enhancements​

Planned Features (v2.0)​

Future Vision (v3.0)​

Contributing​