26 KiB
26 KiB
/sdd:command-optimise
Meta
- Version: 2.0
- Category: transformation
- Complexity: moderate
- Purpose: Convert existing slash commands to LLM-optimized format with intelligent auto-detection
Definition
Purpose: Transform slash command documentation into LLM-optimised format by analysing the command's content to determine optimal formatting, then replaces the original command file with the optimised version.
Syntax: /sdd:command-optimise <command_ref> [format_style] [strictness] [--dry-run]
Parameters
| Parameter | Type | Required | Default | Description | Validation |
|---|---|---|---|---|---|
| command_ref | string | Yes | - | Command name (e.g., "/deploy") OR full command documentation text | Non-empty |
| format_style | string | No | "auto" | Output format style | One of: auto, structured, xml, json, imperative, contract |
| strictness | string | No | "auto" | Level of detail and validation rules | One of: auto, minimal, standard, comprehensive |
| --dry-run | flag | No | false | Preview changes without writing to file | Boolean flag |
Behavior
ON INVOCATION:
1. DETERMINE input type and retrieve command documentation:
IF command_ref starts with "/" AND has no spaces/newlines:
// This is a command name reference
SEARCH for command documentation:
- Look in project's /sdd:commands directory
- Check registered command definitions
- Search documentation files
- Query command registry
IF command found:
SET command_text = retrieved documentation
ELSE:
RETURN "Error: Command '{command_ref}' not found. Please provide the full command text."
ELSE:
// This is the full command documentation
SET command_text = command_ref
2. PARSE command documentation:
- Extract command name (look for /sdd:command patterns)
- Identify any existing parameters/arguments
- Find usage examples if present
- Detect implicit behavior from description
- Extract action verbs and keywords from documentation
3. ANALYZE command content to determine optimal configuration:
EXAMINE command documentation for indicators:
// Check for STATE MODIFICATION indicators
STATE_MODIFYING_INDICATORS = [
"saves", "writes", "updates", "modifies", "changes", "deletes", "removes",
"creates", "inserts", "deploys", "publishes", "commits", "persists",
"alters", "mutates", "transforms production", "affects live"
]
// Check for SECURITY/CRITICAL indicators
SECURITY_INDICATORS = [
"authenticate", "authorize", "encrypt", "decrypt", "password", "token",
"certificate", "permission", "access control", "security", "vulnerability",
"sensitive", "credential", "private key", "secret"
]
// Check for ANALYSIS/INSPECTION indicators
ANALYSIS_INDICATORS = [
"analyzes", "scans", "inspects", "examines", "profiles", "measures",
"benchmarks", "evaluates", "assesses", "diagnoses", "investigates",
"reports on", "collects metrics", "gathers data"
]
// Check for VALIDATION/TESTING indicators
VALIDATION_INDICATORS = [
"tests", "validates", "verifies", "checks", "asserts", "ensures",
"confirms", "proves", "quality assurance", "QA", "unit test",
"integration test", "e2e", "smoke test"
]
// Check for CONFIGURATION indicators
CONFIG_INDICATORS = [
"configures", "sets up", "initializes", "options", "settings",
"preferences", "environment", "parameters", "flags", "toggles"
]
// Check for SEARCH/QUERY indicators
SEARCH_INDICATORS = [
"searches", "finds", "queries", "lists", "fetches", "retrieves",
"gets", "selects", "filters", "looks up", "discovers"
]
// Check for DOCUMENTATION indicators
DOC_INDICATORS = [
"documents", "generates docs", "creates documentation", "API spec",
"readme", "comments", "annotates", "describes", "explains"
]
// Analyze parameter complexity
PARAM_COMPLEXITY = COUNT(parameters) +
COUNT(nested_params) * 2 +
COUNT(optional_params) * 0.5
// Analyze behavior complexity
BEHAVIOR_COMPLEXITY = COUNT(steps) +
COUNT(conditionals) * 2 +
COUNT(error_cases)
// DECISION TREE for format selection:
IF (contains STATE_MODIFYING_INDICATORS && contains("production|live|database")):
format = "contract" // Need guarantees
strictness = "comprehensive"
reason = "Command modifies production state - requires strict pre/post conditions"
ELSE IF (contains SECURITY_INDICATORS):
format = "contract" // Security needs guarantees
strictness = "comprehensive"
reason = "Security-sensitive command - requires comprehensive validation"
ELSE IF (contains VALIDATION_INDICATORS && BEHAVIOR_COMPLEXITY > 5):
format = "contract" // Complex testing needs clear contracts
strictness = "comprehensive"
reason = "Complex validation logic - benefits from GIVEN/WHEN/THEN structure"
ELSE IF (contains ANALYSIS_INDICATORS && mentions("step|phase|process")):
format = "imperative" // Multi-step analysis
strictness = "comprehensive"
reason = "Multi-step analysis process - suits INSTRUCTION/PROCESS format"
ELSE IF (PARAM_COMPLEXITY > 8 || has_nested_objects):
format = "json" // Complex parameters
strictness = "standard"
reason = "Complex parameter structure - JSON schema provides clarity"
ELSE IF (contains CONFIG_INDICATORS && has_multiple_options):
format = "json" // Configuration with options
strictness = "standard"
reason = "Configuration command with multiple options - JSON format ideal"
ELSE IF (contains DOC_INDICATORS):
format = "xml" // Rich documentation
strictness = "comprehensive"
reason = "Documentation generation - XML provides rich metadata structure"
ELSE IF (contains SEARCH_INDICATORS && PARAM_COMPLEXITY < 3):
format = "json" // Simple search
strictness = "minimal"
reason = "Simple search/query command - minimal JSON sufficient"
ELSE IF (BEHAVIOR_COMPLEXITY < 3 && PARAM_COMPLEXITY < 3):
format = "structured" // Simple command
strictness = "minimal"
reason = "Simple utility command - basic structure sufficient"
ELSE IF (contains("build|compile|make|bundle")):
format = "imperative" // Build process
strictness = "standard"
reason = "Build process - benefits from step-by-step PROCESS format"
ELSE:
format = "structured" // Default fallback
strictness = "standard"
reason = "Standard command - balanced structure and detail"
4. LOG analysis decision:
```
Command Analysis Results:
━━━━━━━━━━━━━━━━━━━━━━━━
Detected Characteristics:
- State Modification: [Yes/No] {indicators found}
- Security Concerns: [Yes/No] {indicators found}
- Parameter Complexity: [Low/Medium/High] (score: X)
- Behavior Complexity: [Low/Medium/High] (score: Y)
- Primary Function: [category]
Selected Configuration:
- Format: [format_style]
- Strictness: [strictness]
- Reasoning: [detailed explanation]
```
5. TRANSFORM to selected format_style:
IF format_style="structured":
- Use markdown headers with consistent hierarchy
- Add parameter table with types
- Include behavior steps
- Add examples section
IF format_style="xml":
- Wrap in XML-style tags
- Separate purpose, syntax, parameters, behavior
- Include constraints section
IF format_style="json":
- Convert to JSON schema format
- Include type definitions
- Add execution_steps array
IF format_style="imperative":
- Use INSTRUCTION/PROCESS format
- Add INPUTS/OUTPUTS sections
- Include RULES with MUST/SHOULD/NEVER
IF format_style="contract":
- Use GIVEN/WHEN/THEN format
- Add PRECONDITIONS/POSTCONDITIONS
- Include INVARIANTS
6. ENHANCE based on strictness:
IF strictness="minimal":
- Add only essential missing elements
- Basic type annotations
- Simple examples
IF strictness="standard":
- Complete parameter documentation
- Validation rules
- Error handling section
- Multiple examples
IF strictness="comprehensive":
- Detailed type specifications
- Edge case handling
- Performance considerations
- Version information
- Related commands
- Security considerations (if applicable)
- Rollback procedures (if state-modifying)
7. VALIDATE converted documentation:
- Ensure all parameters are documented
- Verify examples match syntax
- Check for ambiguous instructions
8. WRITE optimised command to file:
IF --dry-run flag is set:
DISPLAY preview of changes:
```
DRY RUN - No files will be modified
────────────────────────────────────
Original file: /commands/deploy.md
Format: contract
Strictness: comprehensive
Preview of changes:
[Show diff or preview]
To apply changes, run without --dry-run
```
ELSE:
// Create backup of original
IF command was loaded from file:
COPY original to "{filename}.backup-{timestamp}"
LOG "Backup created: {backup_path}"
// Determine output path
IF command_ref was a name reference:
SET output_path = original file location
ELSE:
// For text input, create new file
SET output_path = "/commands/{command_name}.md"
// Write optimised version
WRITE optimised documentation to output_path
// Log the update
GENERATE update report:
```
✅ Command Successfully Optimised
═══════════════════════════════════
Command: {command_name}
Original: {original_path}
Backup: {backup_path}
Updated: {output_path}
Format Applied: {format_style}
Strictness: {strictness_level}
Timestamp: {iso_timestamp}
Changes Applied:
- Added type annotations to {n} parameters
- Generated {n} usage examples
- Added {validation_rules} validation rules
- Created {sections} new documentation sections
File has been updated in place.
To revert: mv {backup_path} {output_path}
```
9. RETURN confirmation with analysis report and file paths
Examples
Example 1: Replace Command File
INPUT:
/sdd:command-optimise /deploy
PROCESS:
→ Retrieved documentation from /commands/deploy.md
→ Created backup: /commands/deploy.md.backup-20250127-143022
→ Analysed and optimised command
→ Wrote optimised version to /commands/deploy.md
OUTPUT:
✅ Command Successfully Optimised
═══════════════════════════════════
Command: /deploy
Original: /commands/deploy.md
Backup: /commands/deploy.md.backup-20250127-143022
Updated: /commands/deploy.md
Format Applied: contract
Strictness: comprehensive
Timestamp: 2025-01-27T14:30:22Z
Changes Applied:
- Added type annotations to 5 parameters
- Generated 3 usage examples
- Added 8 validation rules
- Created 4 new documentation sections
File has been updated in place.
To revert: mv /commands/deploy.md.backup-20250127-143022 /commands/deploy.md
Example 2: Dry Run Preview
INPUT:
/sdd:command-optimise /api-call json comprehensive --dry-run
PROCESS:
→ Retrieved documentation from /commands/api-call.md
→ Analysed and optimised command
→ DRY RUN MODE - No files modified
OUTPUT:
DRY RUN - No files will be modified
────────────────────────────────────
Original file: /commands/api-call.md
Format: json (manually specified)
Strictness: comprehensive (manually specified)
Preview of changes:
- FROM: Simple text documentation
- TO: Full JSON schema with type definitions
- Added: Error handling section
- Added: 5 usage examples
- Added: Parameter validation rules
[Shows preview of optimised content]
To apply changes, run without --dry-run:
/sdd:command-optimise /api-call json comprehensive
Example 3: Create New File from Text
INPUT:
/sdd:command-optimise "
/process-data - handles user data
Takes input file, transforms it, and saves the results to the database.
Can update existing records or create new ones.
"
PROCESS:
→ Detected full command documentation (contains spaces/newlines)
→ Analyzing provided text directly
ANALYSIS:
✓ Found state modification indicators: "saves", "database", "update"
[Continues with normal analysis...]
Example 4: Command Not Found
INPUT:
/sdd:command-optimise /unknown-command
PROCESS:
→ Detected command name reference: "/unknown-command"
→ Searching command registry...
→ Command not found
OUTPUT:
Error: Command '/unknown-command' not found. Please provide the full command text or ensure the command name is correct.
Example 5: Auto-Detects State Modification in Retrieved Command
INPUT:
/sdd:command-optimise /migrate-db
PROCESS:
→ Retrieved from: /commands/migrate-db.md
→ Created backup: /commands/migrate-db.md.backup-20250127-143045
ANALYSIS:
✓ Found state modification indicators: "migrations", "updates", "schema"
✓ Found database indicators: "database", "schema"
✓ Detected: Database migration command
✓ Applied: contract format + comprehensive strictness
✓ Reasoning: Database changes need strict pre/post conditions
OUTPUT:
✅ Command Successfully Optimised
═══════════════════════════════════
Command: /migrate-db
Original: /commands/migrate-db.md
Backup: /commands/migrate-db.md.backup-20250127-143045
Updated: /commands/migrate-db.md
Format Applied: contract
Strictness: comprehensive
File has been updated in place.
✓ Applied: contract format + comprehensive strictness
✓ Reasoning: Command modifies database state - requires strict pre/post conditions
OUTPUT:
CONTRACT: Data Processing Command
GIVEN: Input file with user data to process
WHEN: The /process-data command is invoked
THEN: Data is transformed and persisted to database
PRECONDITIONS:
✓ Input file exists and is readable
✓ File format is valid (CSV/JSON/XML)
✓ Database connection is available
✓ User has write permissions
✓ Sufficient storage space available
ACTIONS:
→ Validate input file format
→ Parse and load data into memory
→ Apply transformation rules
→ Check for existing records
→ IF existing: Update with new values
→ ELSE: Create new records
→ Commit transaction to database
→ Generate operation report
POSTCONDITIONS:
✓ All valid data is saved to database
✓ Invalid records are logged
✓ Transaction is atomic (all or nothing)
✓ Audit trail is updated
✓ Report contains success/failure counts
INVARIANTS:
• Data integrity is maintained
• No partial updates on failure
• Original file is never modified
• Database constraints are respected
Example 6: Auto-Detects Complex Parameters
INPUT:
/optimize-command "
/api-call - makes HTTP requests
Parameters:
- url: target endpoint
- method: GET, POST, PUT, DELETE
- headers: object with header key-values
- body: nested JSON payload
- auth: {type: 'bearer'|'basic', credentials: {...}}
- retry: {attempts: number, delay: number}
"
ANALYSIS:
✓ Parameter complexity score: 12 (6 params, 3 nested objects)
✓ Detected: Complex parameter structure
✓ Applied: json format + standard strictness
✓ Reasoning: Complex nested parameters - JSON schema provides clarity
OUTPUT:
{
"command": "/api-call",
"description": "Execute HTTP requests with configurable options",
"parameters": {
"url": {
"type": "string",
"required": true,
"description": "Target endpoint URL",
"pattern": "^https?://.+"
},
"method": {
"type": "string",
"required": false,
"default": "GET",
"enum": ["GET", "POST", "PUT", "DELETE", "PATCH"]
},
"headers": {
"type": "object",
"required": false,
"description": "HTTP headers as key-value pairs",
"additionalProperties": {"type": "string"}
},
"body": {
"type": "object",
"required": false,
"description": "Request body for POST/PUT requests"
},
"auth": {
"type": "object",
"required": false,
"properties": {
"type": {"enum": ["bearer", "basic"], "required": true},
"credentials": {
"type": "object",
"properties": {
"token": {"type": "string"},
"username": {"type": "string"},
"password": {"type": "string"}
}
}
}
},
"retry": {
"type": "object",
"required": false,
"properties": {
"attempts": {"type": "integer", "minimum": 1, "maximum": 5},
"delay": {"type": "integer", "minimum": 100, "maximum": 5000}
}
}
},
"execution_steps": [
"Validate URL format",
"Configure authentication if provided",
"Set request headers",
"Prepare request body if applicable",
"Execute HTTP request with retry logic",
"Handle response or errors",
"Format and return results"
],
"error_handling": {
"invalid_url": "Return error: 'Invalid URL format'",
"network_error": "Retry according to retry config, then fail",
"auth_failure": "Return 401 with auth error details",
"timeout": "Retry with exponential backoff"
}
}
Example 3: Auto-Detects Multi-Step Process
INPUT:
/optimize-command "
/analyze-codebase
Performs code analysis in three phases:
1. First scans all files for syntax errors
2. Then checks for code smells and anti-patterns
3. Finally generates a detailed report with metrics
Each phase must complete before the next begins.
"
ANALYSIS:
✓ Found analysis indicators: "analyzes", "scans", "checks", "report", "metrics"
✓ Detected multi-step process: "phases", "First", "Then", "Finally"
✓ Behavior complexity: High (3 phases + sequencing)
✓ Applied: imperative format + comprehensive strictness
✓ Reasoning: Multi-step analysis process - suits INSTRUCTION/PROCESS format
OUTPUT:
/analyze-codebase
INSTRUCTION: Perform comprehensive codebase analysis in sequential phases
INPUTS:
- path: Root directory to analyze (required)
- config: Analysis configuration file (optional, default: .analysis.yml)
- output: Report output format [json|html|markdown] (optional, default: markdown)
- exclude: Patterns to exclude from analysis (optional)
PROCESS:
Phase 1: Syntax Analysis
1. SCAN all source files in specified path
2. IDENTIFY file types by extension
3. FOR EACH file:
- PARSE using language-specific parser
- COLLECT syntax errors with line numbers
- TRACK warning-level issues
4. IF errors found THEN log to phase1_errors.log
5. PROCEED only if no blocking errors
Phase 2: Code Quality Analysis
1. LOAD code smell detection rules
2. FOR EACH validated file:
- CHECK for duplicated code blocks
- IDENTIFY complex methods (cyclomatic complexity > 10)
- DETECT anti-patterns specific to language
- MEASURE code coverage if tests present
3. AGGREGATE findings by severity
4. CALCULATE quality score per file
Phase 3: Report Generation
1. COMPILE all findings from Phase 1 and 2
2. GENERATE metrics:
- Total lines of code
- Technical debt estimation
- Complexity distribution
- Issue density by module
3. CREATE visualizations if HTML output
4. FORMAT report according to output parameter
5. WRITE report to specified location
OUTPUT FORMAT:
Code Analysis Report Generated: [timestamp]
Phase 1: Syntax Results
- Files Scanned: X
- Syntax Errors: Y
- Warnings: Z
Phase 2: Quality Findings
- Critical Issues: A
- Major Issues: B
- Minor Issues: C
- Quality Score: X/100
Phase 3: Metrics [Detailed metrics table]
RULES:
- MUST complete each phase before proceeding
- NEVER analyze binary files
- SHOULD respect .gitignore patterns by default
- MUST handle large codebases incrementally
- ALWAYS provide progress indicators
Example 4: Auto-Detects Security Concerns
INPUT:
/optimize-command "
/rotate-keys
Updates API keys and certificates. Handles sensitive credential rotation.
Requires admin authentication. Modifies production secrets.
"
ANALYSIS:
✓ Found security indicators: "keys", "certificates", "credential", "authentication", "secrets"
✓ Found state modification: "Updates", "Modifies", "production"
✓ Detected: Security-critical state modification
✓ Applied: contract format + comprehensive strictness
✓ Reasoning: Security-sensitive command modifying production - requires maximum safety
OUTPUT:
CONTRACT: Secure Key Rotation Command
GIVEN: Valid admin credentials and keys to rotate
WHEN: The /rotate-keys command is invoked with proper authorization
THEN: Keys are rotated securely with zero downtime
PRECONDITIONS:
✓ User has admin-level authentication
✓ Multi-factor authentication completed
✓ Audit logging is enabled
✓ Backup of current keys exists
✓ No active operations using current keys
✓ Key rotation window is open
✓ All dependent services notified
ACTIONS:
→ Verify admin authorization
→ Create encrypted backup of current keys
→ Generate new keys with proper entropy
→ Update keys in secure vault
→ Propagate to dependent services
→ Verify service connectivity
→ Mark old keys for deprecation
→ Update audit log
POSTCONDITIONS:
✓ New keys are active in all systems
✓ Old keys remain valid for grace period
✓ All services operational with new keys
✓ Audit trail complete with timestamp
✓ Backup is encrypted and stored
✓ Rollback plan is documented
INVARIANTS:
• Zero downtime during rotation
• Keys never exposed in logs
• Audit trail is immutable
• Encryption at rest and in transit
SECURITY CONSTRAINTS:
- MUST use hardware security module if available
- NEVER log key values
- ALWAYS use secure random generation
- MUST notify security team on completion
- REQUIRES two-person authorization for production
Auto-Detection Logic
The command analyzes the CONTENT of your existing command documentation to determine optimal format:
🔍 What It Looks For:
-
State Modification →
contract + comprehensive- Words like: saves, writes, updates, modifies, deletes, deploys
- Mentions: database, production, live system
-
Security/Sensitive Operations →
contract + comprehensive- Words like: authenticate, encrypt, password, token, credential
- Mentions: security, permission, secret, private key
-
Multi-Step Processes →
imperative + comprehensive- Structure: "Phase 1... Phase 2..." or "First... Then... Finally..."
- Words like: analyzes, scans, processes, evaluates + step indicators
-
Complex Parameters →
json + standard- Multiple nested objects
- Arrays of options
- 5+ parameters with complex types
-
Simple Queries →
json + minimal- Words like: search, find, get, list, query
- Few parameters (<3)
- No state modification
-
Simple Utilities →
structured + minimal- Basic operations
- Minimal parameters
- No complex behavior
📊 Complexity Scoring:
- Parameter Complexity = base params + (nested × 2) + (optional × 0.5)
- Behavior Complexity = steps + (conditionals × 2) + error cases
- High complexity → More comprehensive documentation needed
Constraints
- ⛔ NEVER discard existing information from the original command
- ⚠️ ALWAYS preserve original command name exactly as provided
- ✅ MUST add type information for all parameters
- ✅ MUST include at least one usage example
- 📝 SHOULD infer missing details from context when possible
- 🔍 SHOULD flag ambiguities for user review
Error Handling
- If command_text is empty: Return "Error: No command text provided"
- If no command name detected: Return "Error: Could not identify command name (expected /sdd:command format)"
- If format_style invalid: Return "Error: Unknown format style. Use: auto, structured, xml, json, imperative, or contract"
- If parsing fails: Return partial optimization with warnings about unparseable sections
Usage Patterns
Quick Command Reference
# Optimise a command by name only
/sdd:command-optimise /deploy
# Optimise with specific format
/sdd:command-optimise /api-call json
# Optimise with format and strictness
/sdd:command-optimise /security-scan imperative comprehensive
# Provide full text when command isn't in registry
/sdd:command-optimise "
/custom-command - does something special
Parameters: input, output, options
Behavior: processes input and produces output
"
Command Name Detection Logic
The system determines if input is a command name reference by checking:
- Starts with "/" character
- Contains no spaces or newlines (single token)
- Looks like a command name pattern (/word-word)
If these conditions are met, it searches for the command documentation. Otherwise, it treats the input as the full command text to analyze.
Notes
- Command names are searched in the project's command registry
- If a command isn't found by name, provide the full documentation text
- Manual format/strictness override works with both name references and full text
- The optimiser analyses actual command content, not just the command name