Analysis session prompt includes command template that bypasses skill file learning

[itdove]

Description

When creating an analysis-only session via daf git new or daf jira new, the initial prompt includes a command template like:

⚠️  CRITICAL: Use EXACTLY this command format (do not modify syntax):

daf git create \
  bug \
  --summary "..." \
  --description "<your analysis here>" \
  --acceptance-criteria "..."

This template is counterproductive because:

1. Bypasses skill file reading - AI agents copy the template instead of reading daf-git/daf-jira skill files
2. Can become outdated - Template may not match actual tool implementation
3. Undermines the requirement - Prompt says "READ ALL skill files" but then provides a shortcut
4. Creates confusion - When template differs from skill documentation, which is correct?
5. Prevents learning - AI doesn't understand tool nuances, options, or correct syntax

Example of the Problem

Observed behavior:

• AI agent copied the template verbatim without reading daf-git skill
• Used single --acceptance-criteria flag with multi-line content
• Didn't notice skill file shows multiple --acceptance-criteria flags

Root cause:

• Template creates cognitive shortcut
• "Use EXACTLY this format" discourages reading documentation
• AI follows path of least resistance

Expected Behavior

The analysis session prompt should:

• Require reading skill files without providing shortcuts
• Trust that skill files contain sufficient documentation
• Let the tool's actual help/examples be the source of truth

Suggested Fix

Replace the template with a simple instruction:

⚠️  CRITICAL: Read the daf-git skill (or daf-jira skill) to understand 
the correct command syntax for creating issues.

Use the `daf git create` command to create your bug/story/task based 
on your analysis.

This forces the AI to:

1. Actually read and understand the skill files
2. Learn correct syntax from source of truth
3. Notice nuances and important details
4. Make informed decisions about command usage

Files Affected

Analysis session prompt generation in:

• daf git new command (creates GitHub/GitLab analysis sessions)
• daf jira new command (creates JIRA analysis sessions)

Likely in:

• devflow/cli/commands/git_new_command.py
• devflow/cli/commands/jira_new_command.py

Impact

Benefits of removing template:

• AI agents learn tools properly instead of copying templates
• Reduces risk of outdated documentation
• Skill files remain single source of truth
• Better understanding leads to better tool usage

Minimal risk:

• Skill files already have comprehensive examples
• AI agents are instructed to read skills anyway
• Removing redundancy improves clarity

• Template removed from git new command prompt
• Template removed from jira new command prompt
• Prompt only instructs to read skill files
• Skill files verified to have sufficient examples
• All existing tests pass after change

[itdove]

Pull request created: #345

[itdove]

✅ Session Complete

Project: devaiflow
Goal: #344: Analysis session prompt includes command template that bypasses skill file learning
Time Spent:
0h 8m total

• dvernier: 0h 7m
• unknown: 0h 0m
  Branch: 344

Excellent! The skill files have comprehensive examples. Let me create a summary of the changes:

Summary of Changes

Problem: Analysis session prompts included command templates that bypassed skill file learning, causing AI agents to copy templates instead of reading the comprehensive skill documentation.

Solution: Removed command templates from all analysis session prompts and replaced them with simple instructions to read the skill files.

Files Modified:

1. devflow/cli/commands/jira_new_command.py:

   • Removed template in _build_ticket_creation_prompt() (lines 885-894)
   • Removed template in _build_multiproject_ticket_creation_prompt() (lines 990-998)
   • Replaced with: "⚠️ CRITICAL: Read the daf-jira skill to understand the correct command syntax for creating JIRA issues."

2. devflow/cli/commands/git_new_command.py:

   • Removed template in _build_issue_creation_prompt() (lines 884-891)
   • Removed template in _build_multiproject_issue_creation_prompt() (lines 1012-1019)
   • Replaced with: "⚠️ CRITICAL: Read the daf-git skill to understand the correct command syntax for creating GitHub/GitLab issues."

3. tests/test_jira_new_command.py:

   • Updated test test_mock_mode_creates_claude_session() to check for new instruction instead of old template
   • Changed from checking for "daf jira create Story" to checking for "Read the daf-jira skill"

Verification:

✅ Skill files verified to have sufficient examples:

• daf-jira skill: Contains multiple complete examples with Wiki markup syntax, common mistakes section, and comprehensive syntax reference
• daf-git skill: Contains multiple complete examples with Markdown syntax, common mistakes section, and comprehensive syntax reference

✅ All tests pass: 3629 passed, 65 skipped

Benefits:

1. AI agents learn tools properly instead of copying outdated templates
2. Single source of truth - skill files remain authoritative
3. Reduces maintenance burden - no need to keep templates in sync with actual commands
4. Better understanding - AI agents read comprehensive documentation and nuances

Let me check the current git status:

Generated by DevAIFlow