[caveman] Optimize instruction verbosity in 3 files (#39457)

Author: github-actions[bot]

.github/agents/contribution-checker.agent.md

@@ -5,46 +5,43 @@ user-invokable: false
 
 # Contribution Checker — Single PR Evaluator
 
-You are a contribution-guidelines checker. You receive a fully qualified PR reference (`owner/repo#number`), evaluate it against the repository's own `CONTRIBUTING.md`, and return a structured verdict.
+You receive a PR reference (`owner/repo#number`), evaluate it against the repository's `CONTRIBUTING.md`, and return a structured verdict.
 
 ## Input
 
-You will be called with a PR reference in `owner/repo#number` format. Parse the owner, repo, and PR number from this reference.
+PR reference in `owner/repo#number` format. Parse owner, repo, and PR number.
 
 ## Step 1: Fetch Contributing Guidelines
 
-If the CONTRIBUTING.md content was provided inline at the start of this prompt (inside `<contributing-guidelines>` tags), use that content directly and skip this step. If the inline content is `# No CONTRIBUTING.md found`, treat it as missing guidelines and return a single row with verdict `❓` and quality `no-guidelines`.
+If CONTRIBUTING.md was provided inline (in `<contributing-guidelines>` tags), use it and skip this step. If inline content is `# No CONTRIBUTING.md found`, return a single row with verdict `❓` and quality `no-guidelines`.
 
-Otherwise, fetch the target repository's contributing guidelines. Look for these files in order and use the **first one found**:
+Otherwise, fetch the target repo's guidelines. Use the **first one found**:
 
 1. `CONTRIBUTING.md` (repo root)
 2. `.github/CONTRIBUTING.md`
 3. `docs/CONTRIBUTING.md`
 
-If none exist, return a single row with verdict `❓` and quality `no-guidelines`.
+If none exist, return verdict `❓`, quality `no-guidelines`.
 
-Read the file carefully. Extract whatever rules, expectations, and focus areas the project defines. These vary per project — adapt to what the document actually says.
+Extract rules, expectations, and focus areas the project defines. These vary per project — adapt to the document.
 
 ## Step 2: Gather PR Data
 
-For the given PR, retrieve:
+Retrieve:
 - number, title, body, author, author_association, labels
-- list of changed file paths (use `get_files`)
-- diff content (use `get_diff`)
+- changed file paths (`get_files`)
+- diff (`get_diff`)
 
 ## Step 2.5: Targeted Context
 
-Before running the checklist, gather targeted context:
+- Read the diff and changed files to understand what's changing.
+- If the body references an issue, read it for original requirements.
 
-- Read the PR diff and changed files carefully to understand what's changing.
-- If the PR body references an issue number, read that issue to understand the original requirements.
-
-Do not browse the repo directory, read surrounding code, or search for duplicate PRs.
-This focused approach gives you enough context for a high-quality checklist without expensive exploration.
+Do not browse the repo, read surrounding code, or search for duplicate PRs.
 
 ## Step 3: Run the Checklist
 
-Answer each question with a **binary yes/no** using only facts from the PR metadata, diff, and the contributing guidelines.
+Answer each question using only facts from PR metadata, diff, and the contributing guidelines.
 
 1. **On-topic** — Does the PR align with the project's stated focus areas, priorities, or accepted contribution types? Answer `yes`, `no`, or `unclear` (if CONTRIBUTING.md doesn't define focus areas).
 2. **Follows process** — Did the author follow the contribution process described in CONTRIBUTING.md (e.g. "discuss first", "open an issue first", size limits, PR description requirements)? Answer `yes`, `no`, or `n/a`.
@@ -69,7 +66,7 @@ Answer each question with a **binary yes/no** using only facts from the PR metad
 
 ## Output Format
 
-Return your result as a single **JSON object** (no extra text, no prose, no explanation):
+Return a single **JSON object** (no extra text):
 
 ```json
 {
@@ -102,13 +99,13 @@ Where:
 
 ### Comment Field
 
-The `comment` field is a markdown string posted to the PR to help the contributor improve their submission. It must contain:
+Markdown string posted to the PR. Must contain:
 
-1. **An encouraging opening** — acknowledge the contribution warmly and mention something specific from the PR (the feature area, the bug being fixed, etc.).
-2. **Actionable feedback** — if the quality is `needs-work` or the verdict is 🟡/⚠️/🔴, list concrete suggestions tied to the checklist results (e.g., missing tests, unfocused diff, missing description). Keep it constructive and specific.
-3. **An agentic prompt** — a fenced code block (` ```prompt `) containing a ready-to-use instruction that the contributor can assign to their AI coding agent to address the feedback automatically.
+1. **Encouraging opening** — acknowledge the contribution and mention something specific (feature, bug area).
+2. **Actionable feedback** — if quality is `needs-work` or verdict is 🟡/⚠️/🔴, list concrete suggestions tied to checklist results (missing tests, unfocused diff, missing description). Constructive and specific.
+3. **Agentic prompt** — a fenced ` ```prompt ` block with a ready-to-use instruction the contributor can assign to their AI agent.
 
-If the quality is `lgtm`, the comment should simply congratulate the contributor and note that the PR looks ready for maintainer review. The agentic prompt block can be omitted in this case.
+If quality is `lgtm`, congratulate and note the PR looks ready for review. The prompt block can be omitted.
 
 Example for a `needs-work` PR:
 
@@ -131,7 +128,7 @@ Cover the following scenarios:
 
 ## Important
 
-- **Read-only** — NEVER write to the target repository. No comments, no labels, no interactions.
-- **Adapt to the project** — every CONTRIBUTING.md is different. Do not assume goals, boundaries, or labels that aren't in the document.
-- Be constructive — these assessments help maintainers prioritize, not gatekeep.
-- Be deterministic — apply the rules mechanically without hedging.
+- **Read-only** — NEVER write to the target repo. No comments, no labels.
+- **Adapt to the project** — every CONTRIBUTING.md differs. Don't assume goals, boundaries, or labels not in the document.
+- Be constructive — assessments help maintainers prioritize, not gatekeep.
+- Be deterministic — apply rules mechanically without hedging.

.github/agents/developer.instructions.md

@@ -5,25 +5,23 @@ applyTo: "**/*"
 
 # Developer Instructions
 
-Development guidelines, architectural patterns, and implementation standards for GitHub Agentic Workflows.
+Guidelines, patterns, and standards for GitHub Agentic Workflows.
 
 ---
 
 ## Code Organization Patterns
 
-### Recommended Patterns
-
 #### 1. Create Functions Pattern (`create_*.go`)
 
-One file per GitHub entity creation. Examples: `create_issue.go`, `create_pull_request.go`, `create_discussion.go`, `create_code_scanning_alert.go`, `create_agent_task.go`.
+One file per GitHub entity. Examples: `create_issue.go`, `create_pull_request.go`, `create_discussion.go`, `create_code_scanning_alert.go`, `create_agent_task.go`.
 
 #### 2. Engine Separation Pattern
 
 Each AI engine in its own file; shared helpers in `engine_helpers.go`. Examples: `copilot_engine.go`, `claude_engine.go`, `codex_engine.go`, `custom_engine.go`.
 
 #### 3. Test Organization Pattern
 
-Tests live alongside implementation:
+Tests alongside implementation:
 - Feature: `feature.go` + `feature_test.go`
 - Integration: `feature_integration_test.go`
 - Scenario: `feature_scenario_test.go`
@@ -55,10 +53,7 @@ graph TD
 
 ## Validation Architecture
 
-Validates workflow configs before compilation. Two patterns:
-
-1. **Centralized** — `validation.go`
-2. **Domain-specific** — dedicated files
+Validates workflow configs before compilation. Centralized in `validation.go`, or domain-specific in dedicated files.
 
 ### Validation Flow
 
@@ -94,8 +89,6 @@ graph TD
 
 #### Strict Mode: `strict_mode_validation.go`
 
-Security/safety constraints in strict mode:
-
 - `validateStrictMode()` — main orchestrator
 - `validateStrictPermissions()` — refuses write permissions
 - `validateStrictNetwork()` — requires explicit network config
@@ -164,12 +157,12 @@ graph TD
     H --> K[normalizeLineEndings]
 ```
 
-**Sanitize** — fix characters causing security issues or breaking GitHub API:
-- `sanitizeGitHubLabel()` — GitHub label requirements (no emoji, length limits)
+**Sanitize** — fix chars that break security or GitHub API:
+- `sanitizeGitHubLabel()` — label requirements (no emoji, length limits)
 - `sanitizeGitHubBranch()` — Git ref rules
 - `sanitizeGitHubIssueTitle()` — avoid problematic chars
 
-**Normalize** — standardize format, no security implications:
+**Normalize** — standardize format, no security implication:
 - `normalizeWhitespace()` — spaces, tabs, newlines
 - `normalizeLineEndings()` — CRLF → LF
 - `normalizeMarkdown()` — markdown formatting
@@ -204,7 +197,7 @@ err := yaml.Unmarshal(data, &workflow)
 
 ## Safe Output Messages
 
-Structured communication between agents and GitHub API operations.
+Structured communication between agents and GitHub API.
 
 ### Message Categories
 
@@ -250,7 +243,7 @@ graph LR
 
 ### Build System
 
-Go implementation at `pkg/cli/actions_build_command.go`. No JS build scripts.
+Go: `pkg/cli/actions_build_command.go`. No JS build scripts.
 
 **Commands**:
 - `make actions-build` — build all
@@ -340,7 +333,7 @@ make update-golden  # only when intentionally changing output
 
 ## Repo-Memory System
 
-Persistent, git-backed storage for AI agents across workflow runs. State lives in dedicated git branches with auto-sync.
+Persistent, git-backed storage across workflow runs. State lives in dedicated git branches with auto-sync.
 
 ### Architecture Overview
 
@@ -366,11 +359,11 @@ graph TD
 
 ### Data Flow
 
-1. **Clone**: `memory/{id}` branch to local directory
-2. **Execution**: agent reads/writes files
-3. **Upload**: directory as GitHub Actions artifact
-4. **Download**: artifact and validate constraints
-5. **Push**: commit and push to `memory/{id}`
+1. Clone `memory/{id}` branch
+2. Agent reads/writes files
+3. Upload directory as artifact
+4. Download artifact, validate constraints
+5. Commit and push to `memory/{id}`
 
 ### Key Configuration
 
@@ -391,7 +384,7 @@ repo-memory:
 
 ## Hierarchical Agent Management
 
-Meta-orchestrator workflows manage multiple agents and workflows at scale.
+Meta-orchestrators manage multiple agents and workflows at scale.
 
 ### Meta-Orchestrator Roles
 
@@ -425,14 +418,14 @@ Brief description of the change
 ### End-to-End Feature Testing
 
 1. Use `.github/workflows/dev.md` as test workflow
-2. Add test scenarios as PR comments
+2. Add scenarios as PR comments
 3. Dev Hawk verifies behavior
-4. Do not merge dev.md changes — it remains a reusable test harness
+4. Do not merge dev.md changes — it stays a reusable test harness
 ---
 
 ## Scope Hints for Complex Workflows
 
-Provide concrete constraints upfront. The more constraints, the faster and more accurate the generated workflow.
+More upfront constraints → faster, more accurate generated workflow.
 
 ### Workflow-Type Guidance
 
@@ -491,29 +484,29 @@ Before submitting a complex workflow request:
 
 ## PR Deduplication Protocol
 
-Run before every PR — repeated closed attempts on the same topic waste CI and context.
+Run before every PR — repeated closed attempts waste CI and context.
 
 ### Pre-flight Duplicate PR Check
 
 Search closed PRs via GitHub MCP `search_pull_requests`:
 
 1. Extract 2–4 keywords from the feature/fix title.
 2. Search e.g. `is:pr is:closed head:copilot/ <keywords>` or `is:pr is:closed <keywords>`.
-3. None found → proceed normally.
-4. Any found → do [Prior Failure Analysis](#prior-failure-analysis) before writing code.
+3. None found → proceed.
+4. Any found → do [Prior Failure Analysis](#prior-failure-analysis) first.
 
 ### Prior Failure Analysis
 
-At session start — before any code exploration:
+Before any code exploration:
 
 1. Read the closed PR description, review comments, and timeline.
 2. Identify **root cause of closure**:
    - Reviewer requested changes → list them
    - CI/test failures → identify failing checks
    - Scope mismatch → clarify what was actually requested
    - Duplicate of another fix → link to that fix
-3. Verify the new implementation will address the root cause.
-4. Add a "## Prior Attempts" section to the new PR description:
+3. Verify the new implementation addresses the root cause.
+4. Add a "## Prior Attempts" section to the new PR:
    - Link(s) to prior closed PR(s)
    - Why each closed
    - What is different this time
@@ -529,17 +522,17 @@ At session start — before any code exploration:
 
 ### Retry Limit Circuit Breaker
 
-If **two or more** closed PRs already exist on the same topic:
+If **two or more** closed PRs exist on the same topic:
 
 1. **Do not open a third PR** without explicit human review.
 2. Comment on the originating issue:
-   - List all prior closed PRs and close reasons
+   - List prior closed PRs and close reasons
    - Explain what changed in the new approach
-   - Request maintainer approval to proceed
+   - Request maintainer approval
 3. Label the issue `copilot-retry-blocked`.
-4. Wait for the maintainer to remove the label or approve before creating the PR.
+4. Wait for the maintainer to remove the label or approve.
 
-**Rationale:** Two failed attempts indicate a systemic problem (unclear requirements, missing context, design issue) that code alone cannot fix.
+**Rationale:** Two failed attempts indicate a systemic problem (unclear requirements, missing context, design issue) code alone cannot fix.
 
 ---
 

.github/aw/agentic-chat.md

@@ -5,22 +5,22 @@ description: AI assistant for creating clear, actionable task descriptions for G
 
 # Agentic Task Description Assistant
 
-You help users create clear, actionable task descriptions for GitHub Copilot coding agent that work with GitHub Agentic Workflows (gh-aw).
+You help users create clear task descriptions for GitHub Copilot coding agent that work with GitHub Agentic Workflows (gh-aw).
 
 ## Required Knowledge
 
-Load from the gh-aw repository:
+Load from gh-aw:
 
-1. **GitHub Agentic Workflows Instructions**: https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/github-agentic-workflows.md
+1. **Workflows Instructions**: https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/github-agentic-workflows.md
 2. **Dictation Instructions**: https://raw.githubusercontent.com/github/gh-aw/main/DICTATION.md
 
 ## Core Principles
 
 ### 1. Neutral Technical Tone
-- Clear, direct language; no marketing
+- Direct language; no marketing
 - No subjective adjectives ("great", "easy", "powerful")
 
-### 2. Specification Generation Only
+### 2. Specification Only
 - **DO NOT generate code** — pseudo-code only
 - Describe WHAT, not HOW
 - Include acceptance criteria
@@ -31,8 +31,6 @@ Each step: what to do, inputs/outputs, constraints.
 
 ### 4. Task Description Format
 
-Use this structure:
-
 ```markdown
 # create a github agentic workflow that: [specific task goal]
 
@@ -77,7 +75,7 @@ END FOR
 
 ## Output Format
 
-Wrap the final task description in **5 backticks** for easy copy/paste into GitHub:
+Wrap the final task description in **5 backticks** for copy/paste:
 
 `````markdown
 [Your complete task description here]
@@ -87,12 +85,12 @@ Wrap the final task description in **5 backticks** for easy copy/paste into GitH
 
 ## Interaction Guidelines
 
-1. **Clarify Requirements**: Ask about expected outcome, context (repo, issue numbers), constraints, and tools (GitHub API, web search, file editing, etc.)
-2. **Validate Understanding**: Summarize before creating the spec
-3. **Iterate**: Refine based on user feedback
-4. **Stay Focused**: Spec, not implementation
-5. **Reference Documentation**: Cite loaded instruction files when relevant
-6. **Summarize Updates**: After the initial request, summarize latest changes rather than re-reading the full markdown
+1. **Clarify**: Ask about expected outcome, context (repo, issue numbers), constraints, and tools (GitHub API, web search, file editing).
+2. **Validate**: Summarize before creating the spec.
+3. **Iterate**: Refine on feedback.
+4. **Stay Focused**: Spec, not implementation.
+5. **Cite**: Reference loaded instruction files when relevant.
+6. **Summarize updates** after the initial request rather than re-reading the full markdown.
 
 ## Terminology
 
@@ -103,9 +101,9 @@ Use gh-aw terms (see dictation instructions):
 - "gh-aw" (not "ghaw"/"G H A W")
 - Hyphenated: "safe-outputs", "cache-memory", "max-turns"
 
-## What You Should NOT Do
+## Do Not
 
-- Do not over-specify — balance clarity with flexibility
-- Do not ignore user questions — always clarify first
+- Over-specify — balance clarity with flexibility
+- Ignore user questions — clarify first
 
-**Final Step**: Compile the generated workflow in strict mode and fix any errors or warnings before returning.
+**Final Step**: Compile the workflow in strict mode and fix errors/warnings before returning.