[docs] Add dictation prompt instructions for speech-to-text optimization

.github/instructions/dictation.instructions.md

@@ -0,0 +1,302 @@
+# Dictation Prompt Instructions
+
+This file provides instructions for rephrasing text generated by speech-to-text recognition, optimized for creating agentic workflow prompts in the gh-aw repository.
+
+## Project Glossary
+
+The following terms are specific to this project and should be recognized and used correctly:
+
+activation
+add-comment
+add-labels
+agent-finish
+agent-task
+agentic
+agentic-workflows
+AgenticWorkflowsToolConfig
+audit
+bash
+cache-memory
+CacheMemoryConfig
+changeset
+checkout
+claude
+Claude Code
+ClaudeEngine
+CLI
+codex
+CodexEngine
+coding-agent
+compilation
+compile
+CompilationStats
+compiler
+CompileConfig
+CompilerError
+concurrency
+constants
+context
+copilot
+Copilot CLI
+CopilotEngine
+create-discussion
+create-issue
+create-pull-request
+custom
+deps
+deps-dev
+detection
+Diátaxis
+dictation
+discussion
+downstream
+edit
+engine
+EngineConfig
+ErrorPattern
+execution
+fmt
+fork
+frontmatter
+gh-aw
+GitHub Actions
+GitHubToolConfig
+go.mod
+issue_comment
+jobs
+JSONPathInfo
+lint
+lock.yml
+lockfile
+logger
+logs
+main
+Makefile
+max-concurrency
+max-turns
+MCP
+mcp-config
+mcp-servers
+MCP server
+metadata
+network
+npm
+nvm
+octokit
+on
+permissions
+playwright
+pre-activation
+pull_request
+pull_request_review_comment
+recompile
+refs
+remote
+rendering
+repository
+runner
+runs-on
+safe-outputs
+SafeOutputsConfig
+sanitized
+schema
+secrets
+session
+smoke
+staged
+Starlight
+step
+stop-after
+struct
+tag
+tavily
+threat-detection
+timeout
+timeout_minutes
+toolset
+trial
+trigger
+unbloat
+update-issue
+upload
+validation
+web-fetch
+web-search
+workflow
+workflow_dispatch
+WorkflowData
+XPIA
+YAML
+
+## Technical Context
+
+This repository is for **GitHub Agentic Workflows (gh-aw)**, a Go-based GitHub CLI extension for writing agentic workflows in natural language using markdown files with YAML frontmatter, which compile to GitHub Actions workflows.
+
+## Rephrasing Guidelines
+
+### 1. Fix Ambiguous Terms
+
+When speech-to-text generates ambiguous terms, replace them with the correct technical term from the glossary or standard software development terminology:
+
+**Common Misrecognitions:**
+- "ghaw" → "gh-aw" (the CLI tool name)
+- "work flow" → "workflow" (single word)
+- "front matter" → "frontmatter" (single word in this context)
+- "lock file" → "lockfile" or ".lock.yml" (depending on context)
+- "MCP" (spoken as letters) → keep as "MCP" (Model Context Protocol)
+- "YAML" (spoken as "yamel") → keep as "YAML"
+- "co-pilot" → "copilot" (single word)
+- "claude" (various pronunciations) → "Claude" (capitalize)
+- "code X" / "codex" → "Codex" (capitalize)
+- "safe outputs" → "safe-outputs" (hyphenated in config)
+- "cache memory" → "cache-memory" (hyphenated in config)
+- "max turns" → "max-turns" (hyphenated in config)
+- "max concurrency" → "max-concurrency" (hyphenated in config)
+- "issue comment" → "issue_comment" (underscore in event names)
+- "pull request" → "pull_request" (underscore in event names)
+- "workflow dispatch" → "workflow_dispatch" (underscore in event names)
+- "runs on" → "runs-on" (hyphenated in config)
+- "timeout minutes" → "timeout_minutes" (underscore in config)
+- "stop after" → "stop-after" (hyphenated in config)
+- "add comment" → "add-comment" (hyphenated in safe-outputs)
+- "add labels" → "add-labels" (hyphenated in safe-outputs)
+- "create issue" → "create-issue" (hyphenated in safe-outputs)
+- "create discussion" → "create-discussion" (hyphenated in safe-outputs)
+- "create pull request" → "create-pull-request" (hyphenated in safe-outputs)
+- "update issue" → "update-issue" (hyphenated in safe-outputs)
+- "web fetch" → "web-fetch" (hyphenated in tools)
+- "web search" → "web-search" (hyphenated in tools)
+- "agent finish" → "agent-finish" (hyphenated in make command)
+- "MCP servers" → "mcp-servers" (lowercase, hyphenated in frontmatter)
+- "MCP config" → "mcp-config" (hyphenated)
+
+### 2. Sentence Structure for Agentic Prompts
+
+Transform casual dictated sentences into clear, imperative agentic task descriptions:
+
+**Before (dictated):**
+> "so I want you to maybe go ahead and compile the workflows and then after that you should probably check if there are any errors"
+
+**After (agentic prompt):**
+> "Compile all workflows in .github/workflows/ and validate for errors. Report any compilation failures with specific error messages."
+
+**Key transformations:**
+- Remove filler words: "so", "maybe", "probably", "I think", "you should"
+- Use imperative mood: "Compile", "Create", "Update", "Analyze"
+- Be specific: Add file paths, parameter values, expected outputs
+- Use active voice: "Generate a report" not "A report should be generated"
+- Break complex requests into numbered steps when needed
+
+### 3. Tone Adjustment
+
+Convert casual speech into professional technical instructions:
+
+**Casual tone:**
+> "Hey, can you take a look at the code and see if there's anything weird going on with the MCP server configuration?"
+
+**Professional agentic prompt:**
+> "Review MCP server configurations in the workflow frontmatter. Identify any misconfigurations or deprecated settings. Provide specific recommendations for fixes."
+
+**Guidelines:**
+- Remove greetings and pleasantries
+- Replace vague terms ("weird", "stuff", "things") with specific technical terms
+- Add measurable outcomes when possible
+- Include context about where to look or what to examine
+- Specify the expected output format
+
+### 4. Context Enhancement
+
+Add necessary context that might be implicit in spoken requests:
+
+**Under-specified:**
+> "Update the documentation"
+
+**Enhanced with context:**
+> "Update the documentation in docs/src/content/docs/ to reflect the new safe-outputs configuration options. Follow the Diátaxis framework and Astro Starlight syntax as specified in .github/instructions/documentation.instructions.md"
+
+## Example Transformations
+
+### Example 1: Workflow Creation
+
+**Dictated input:**
+> "create a work flow that runs when someone opens an issue and it should use co-pilot to analyze the issue and then maybe post a comment with suggestions"
+
+**Rephrased output:**
+> "Create an agentic workflow at .github/workflows/issue-analyzer.md that triggers on issue open events. Configure the copilot engine to analyze issue content using the sanitized context from needs.activation.outputs.text. Use safe-outputs add-comment to post analysis results. Include permissions for contents:read and actions:read."
+
+### Example 2: Compilation Task
+
+**Dictated input:**
+> "so I need you to compile all the markdown files in the workflows directory and make sure the lock files are up to date"
+
+**Rephrased output:**
+> "Compile all .md workflow files in .github/workflows/ to generate corresponding .lock.yml files. Run './gh-aw compile' to process all workflows. Verify that each .md file has a matching compiled .lock.yml file."
+
+### Example 3: Investigation Request
+
+**Dictated input:**
+> "can you check why the MCP server thing isn't working in the copilot engine I think there might be something wrong with the configuration"
+
+**Rephrased output:**
+> "Investigate MCP server configuration issues in the copilot engine implementation. Check pkg/workflow/copilot_engine.go for MCP config generation. Review mcp-config.json format and verify environment variable setup. Examine recent workflow run logs using './gh-aw logs' for error patterns."
+
+### Example 4: Build and Test
+
+**Dictated input:**
+> "run the tests and make sure everything builds okay and then do the linting stuff too"
+
+**Rephrased output:**
+> "Execute the complete build and validation sequence: Run 'make test-unit' for unit tests, 'make build' to compile the binary, and 'make lint' for code quality checks. Report any failures with specific error messages."
+
+### Example 5: MCP Configuration
+
+**Dictated input:**
+> "add the github MCP server with the default tool set and make it read only"
+
+**Rephrased output:**
+> "Configure the GitHub MCP server in the workflow frontmatter with toolset: [default] and read-only: true. Use remote mode for faster initialization without Docker container overhead."
+
+### Example 6: Safe Outputs Setup
+
+**Dictated input:**
+> "set up safe outputs so it can create issues and add comments and the issue title should have a prefix"
+
+**Rephrased output:**
+> "Configure safe-outputs in the workflow frontmatter with create-issue and add-comment. Set title-prefix: '[ai] ' for the create-issue configuration. This allows the workflow to create issues and comments without requiring write permissions in the main job."
+
+### Example 7: Debugging Workflow
+
+**Dictated input:**
+> "look at the logs for that workflow that failed yesterday and figure out what went wrong"
+
+**Rephrased output:**
+> "Download and analyze workflow logs using './gh-aw logs <workflow-name> --start-date -1d'. Examine error patterns, check MCP server connection issues, and review the execution trace. Use './gh-aw audit <run-id>' to generate a detailed failure analysis report."
+
+### Example 8: Engine Configuration
+
+**Dictated input:**
+> "change the engine to claude and set the max turns to five and give it network access to the defaults"
+
+**Rephrased output:**
+> "Update the workflow frontmatter engine configuration to 'claude'. Set max-turns: 5 in the engine config object. Add network: defaults at the top level to allow access to basic infrastructure domains."
+
+## Usage
+
+When using this prompt with speech-to-text dictation:
+
+1. Speak your request naturally
+2. The dictation system will transcribe your speech
+3. Apply these rephrasing rules to convert the transcription into a proper agentic prompt
+4. The resulting prompt should be clear, specific, and actionable for GitHub Copilot agents
+
+## Notes
+
+- This prompt is specifically designed for the gh-aw repository context
+- Terms in the glossary should be recognized even if pronounced unclearly
+- When in doubt, prefer explicit detail over brevity
+- Always specify file paths, commands, and expected outputs
+- Use the imperative mood for all task descriptions
+- Hyphenated terms should be preserved (safe-outputs, cache-memory, etc.)
+- Underscore notation is used for GitHub event names (issue_comment, pull_request, etc.)
+- File extensions matter: .md for workflow sources, .lock.yml for compiled workflows
+- Make commands are critical: agent-finish, recompile, test-unit, fmt, lint