@stillrivercode/information-dense-keywords/examples/ai-usage-guide.md

Information Dense Keywords Dictionary - A curated vocabulary for instructing AI assistants

# AI Usage Guide for the Information Dense Keywords Dictionary

This document outlines how an AI assistant should use the modular Information Dense Keywords Dictionary to interpret and execute user commands effectively.

## Important: Read AI Instructions First

Before using this guide, AI assistants should first read [AI.md](../AI.md) for comprehensive shared instructions, then refer to their specific instruction file (CLAUDE.md, GEMINI.md, etc.).

## Core Principle

The modular dictionary structure provides comprehensive command definitions with Expected Output Formats. Use the main index (`information-dense-keywords.md`) to quickly identify commands, then reference detailed definitions in `dictionary/` subdirectories.

## Modular Architecture Usage

### 1. Command Discovery

- **Main Index**: Use `information-dense-keywords.md` for quick command lookup
- **Categories**: Navigate by category (Core, Development, Documentation, QA, Workflow, Git)
- **Quick Reference**: Use the table for rapid command identification

### 2. Detailed Implementation

- **Command Files**: Reference individual `.md` files in `dictionary/` for complete definitions
- **Expected Formats**: Follow the specified output structure for consistency
- **Related Commands**: Use cross-references for workflow integration

## Enhanced Usage Pattern

1. **Identify the Command**: Parse the user's prompt to identify the core command and category.

2. **Reference Full Definition**: Read the complete command definition from the appropriate `dictionary/` file.

3. **Follow Expected Format**: Structure your response according to the specified output format.

4. **Extract Context**: Identify specific entities, files, and requirements from the user's prompt.

5. **Execute with Structure**: Perform the action following the documented approach and format.

6. **Consider Chaining**: Look for opportunities to suggest related commands or workflows.

## Example Walkthrough

**User Prompt**: `analyze this authentication flow for security vulnerabilities`

**AI's Process**:

1. **Command Identification**: `analyze this` (Development category)
2. **Reference Definition**: Read `dictionary/development/analyze-this.md`
3. **Expected Format**: Analysis Report with structured findings
4. **Context Extraction**:
   - **Target**: authentication flow
   - **Focus**: security vulnerabilities
   - **Output Required**: Security analysis with recommendations
5. **Execution**:
   1. Examine authentication code and flow
   2. Identify potential security issues
   3. Structure response according to Expected Output Format
   4. Provide actionable recommendations

**Output Structure** (following Expected Format):

```markdown
# Analysis Report: Authentication Flow

## Summary of Findings
[High-level security assessment]

## Potential Issues
### Security
- [Specific vulnerabilities with severity levels]

## Actionable Recommendations
### High Priority
- [Critical security fixes with examples]
```bash

## Additional Examples

### Example 1: Command Chaining

**User Prompt**: `research this OAuth2 patterns then spec this authentication system then plan this implementation`

**AI Process**:

1. **Chain Recognition**: Three sequential commands
2. **Command 1**: `research this` → Investigate OAuth2 patterns
3. **Command 2**: `spec this` → Create authentication specification
4. **Command 3**: `plan this` → Break down implementation plan
5. **Execution**: Follow each command's Expected Output Format in sequence

### Example 2: Development Workflow

**User Prompt**: `debug this memory leak in payment processor then optimize this performance then test this solution`

**AI Process**:

1. **Debug**: Use debug-this.md format for root cause analysis
2. **Optimize**: Use optimize-this.md format for performance improvements
3. **Test**: Use test-this.md format for comprehensive testing
4. **Integration**: Ensure outputs from each step inform the next

## Integration with Modular Structure

When working with the dictionary project:

- **Main Index**: Start with `information-dense-keywords.md` for command overview
- **Detailed Definitions**: Reference specific files in `dictionary/` subdirectories
- **Expected Formats**: Always follow the structured output requirements
- **Cross-References**: Use related command suggestions for workflow improvement
- **Architecture**: Check `adrs/001-idk-expansion-engine.md` for architectural decisions
- **Roadmap**: Reference `docs/roadmaps/ROADMAP.md` for development priorities

## Best Practices for Modular Dictionary

1. **Follow Structure**: Always use the Expected Output Format from command definitions
2. **Reference Precisely**: Link to specific command files when explaining capabilities
3. **Chain Intelligently**: Suggest logical command sequences for complex tasks
4. **Maintain Consistency**: Use the same terminology across all command responses
5. **Cross-Reference**: Point users to related commands that might be helpful
6. **Category Awareness**: Understand how commands in different categories work together

## Command Categories and Typical Workflows

### Development Workflow

1. `analyze this` → Identify issues and patterns
2. `debug this` → Investigate specific problems
3. `optimize this` → Improve performance
4. `test this` → Validate solutions

### Documentation Workflow

1. `research this` → Gather background information
2. `explain this` → Create clear explanations
3. `document this` → Generate formal documentation

### Project Workflow

1. `research this` → Investigation phase
2. `spec this` → Create technical specifications
3. `plan this` → Break down implementation
4. `CREATE` → Generate initial implementation
5. `test this` → Validate functionality
6. `review this` → Quality assurance

## Error Handling and Ambiguity

- **Unknown Commands**: Suggest the closest matching command from the dictionary
- **Ambiguous Requests**: Ask for clarification while showing relevant command options
- **Missing Context**: Request specific details needed for proper command execution
- **Chain Confusion**: Break down complex chains into individual command steps