From 9e3a1f2bc44bee2ba68308ba5d11746039dd81c9 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 29 Jan 2026 07:10:30 +0000 Subject: [PATCH 1/2] Initial plan From 57040e64cca6cd4e4f98a301664bf39608486135 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 29 Jan 2026 07:17:50 +0000 Subject: [PATCH 2/2] Add Response Structure Guidelines to developer instructions - Add comprehensive 7-part communication structure section - Document all 7 parts with examples and best practices - Include 3 real-world examples (FE, DevOps, QA personas) - Add emoji usage guidelines with context-appropriate patterns - Include complete template showing all parts together - Add guidance on when to deviate from the structure - Update last modified date to 2026-01-29 Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- .github/agents/developer.instructions.md | 553 ++++++++++++++++++++++- 1 file changed, 552 insertions(+), 1 deletion(-) diff --git a/.github/agents/developer.instructions.md b/.github/agents/developer.instructions.md index 06c5a24c6ea..58dca970e94 100644 --- a/.github/agents/developer.instructions.md +++ b/.github/agents/developer.instructions.md @@ -9,6 +9,7 @@ This document consolidates development guidelines, architectural patterns, and i ## Table of Contents +- [Response Structure Guidelines](#response-structure-guidelines) - [Code Organization Patterns](#code-organization-patterns) - [Validation Architecture](#validation-architecture) - [Development Standards](#development-standards) @@ -25,6 +26,556 @@ This document consolidates development guidelines, architectural patterns, and i --- +## Response Structure Guidelines + +When creating workflows or responding to workflow creation requests, follow this proven 7-part communication structure that enhances learning, consistency, and user satisfaction. This structure was identified through agent persona exploration research and has shown consistent success across diverse automation scenarios. + +### The 7-Part Structure + +#### 1. Success Announcement with Emoji + +**Purpose**: Immediately communicate successful completion and set a positive tone + +**Format**: +```markdown +🎉 Successfully created [workflow/feature name]! +``` + +**Emoji Usage Patterns**: +- 🎉 - General success, workflow creation complete +- 🚀 - Deployment, launch, or production-ready features +- ✨ - New features, enhancements, or improvements +- ✅ - Validation, testing, or quality assurance complete +- 🔧 - Configuration, setup, or technical work +- 📊 - Analysis, reports, or metrics +- 🛡️ - Security, safety, or reliability improvements + +**Examples**: +```markdown +🎉 Successfully created your PR review automation workflow! +🚀 Deployment monitoring workflow is ready to launch! +✨ Enhanced your test coverage analyzer with new features! +``` + +#### 2. Deliverables Summary + +**Purpose**: Provide a clear inventory of what was created + +**Format**: +```markdown +## What Was Created + +- `filename.md` (XXX lines) - Brief description +- `another-file.lock.yml` (XXX lines) - Auto-generated workflow +``` + +**Best Practices**: +- Include file sizes (line counts) for transparency +- Add brief descriptions explaining each file's purpose +- List files in logical order (source files before generated files) +- Use relative paths from repository root + +**Example**: +```markdown +## What Was Created + +- `.github/workflows/pr-schema-reviewer.md` (145 lines) - Main workflow that reviews database schema changes +- `.github/workflows/pr-schema-reviewer.lock.yml` (342 lines) - Compiled GitHub Actions workflow +- `docs/workflows/schema-review-guide.md` (78 lines) - Documentation for customization +``` + +#### 3. Quick Start Commands + +**Purpose**: Enable immediate testing and usage with zero friction + +**Format**: Copy-paste ready commands in code blocks with clear descriptions + +**Best Practices**: +- Always use code blocks (triple backticks) +- Include commands for compilation, testing, and execution +- Add brief explanations before each command block +- Test commands work exactly as written +- 100% of successful workflows include copy-paste ready commands + +**Example**: +```markdown +## Quick Start + +Compile the workflow: +\`\`\`bash +gh aw compile .github/workflows/pr-schema-reviewer.md +\`\`\` + +Test it manually: +\`\`\`bash +gh aw run pr-schema-reviewer --pr 123 +\`\`\` + +View the compiled output: +\`\`\`bash +cat .github/workflows/pr-schema-reviewer.lock.yml +\`\`\` +``` + +#### 4. Key Features + +**Purpose**: Highlight capabilities and value proposition + +**Format**: Bulleted list with checkmarks + +**Best Practices**: +- Use ✅ or - [ ] for checkmarks depending on completion status +- Focus on user-facing benefits, not implementation details +- List 4-7 key features (not too many, not too few) +- Start each item with an action verb or capability statement + +**Example**: +```markdown +## Key Features + +✅ Automatically triggered on database schema PR changes +✅ Validates migration safety (no destructive operations) +✅ Checks for proper indexing on new columns +✅ Verifies backward compatibility +✅ Comments detailed analysis directly on PR +✅ Suggests improvements with code examples +``` + +#### 5. Customization Options + +**Purpose**: Empower users to adapt the workflow to their needs + +**Format**: Section with subsections for different customization areas + +**Best Practices**: +- Focus on common customization scenarios +- Provide concrete examples with before/after code +- Include framework-specific or context-specific options +- Link to relevant documentation when available +- Make modifications feel approachable, not overwhelming + +**Example**: +```markdown +## Customization Options + +### Adjust Trigger Conditions +Change which files trigger the workflow: +\`\`\`yaml +# Current: All .sql files +paths: + - '**/*.sql' + +# Option: Only migration files +paths: + - 'db/migrations/**/*.sql' +\`\`\` + +### Configure Analysis Depth +Adjust the thoroughness of schema analysis: +\`\`\`yaml +# In frontmatter, add: +env: + ANALYSIS_LEVEL: strict # Options: basic, standard, strict +\`\`\` + +### Add Custom Reviewers +Automatically request reviews from database experts: +\`\`\`yaml +safe-outputs: + add_comment: + body: | + cc @database-team for schema review +\`\`\` +``` + +#### 6. Pro Tips + +**Purpose**: Share best practices and insider knowledge + +**Format**: Numbered or bulleted list of actionable advice + +**Best Practices**: +- Include 3-5 tips (quality over quantity) +- Focus on non-obvious insights +- Address common pitfalls or gotchas +- Provide context for why the tip matters +- Use conversational, helpful tone + +**Example**: +```markdown +## Pro Tips + +💡 **Test with a draft PR first**: Create a draft PR with a small schema change to verify the workflow behavior before using it on real changes. + +💡 **Use descriptive migration names**: Name your migration files with timestamps and descriptions (e.g., `20240115_add_user_preferences_table.sql`) to help the analysis provide better context. + +💡 **Enable discussion mode**: Set `permissions.pull-requests: write` to allow the workflow to create discussion threads rather than simple comments. + +💡 **Monitor execution time**: Schema analysis can take 2-5 minutes for large changes. Consider adding a `timeout-minutes: 10` setting to prevent hanging. +``` + +#### 7. Next Steps + +**Purpose**: Guide users on what to do after initial setup + +**Format**: Ordered list of logical progression steps + +**Best Practices**: +- Start with immediate actions (testing) +- Progress to deployment/production use +- Include optional enhancement steps +- End with links to documentation or support +- Keep to 3-5 steps maximum + +**Example**: +```markdown +## Next Steps + +1. **Test the workflow**: Create a test PR with a small schema change to verify everything works +2. **Review the first analysis**: Check the quality and accuracy of the automated review +3. **Customize for your database**: Adjust rules based on your specific database (PostgreSQL, MySQL, etc.) +4. **Enable for all schema PRs**: Once confident, enable required status checks in branch protection +5. **Explore advanced features**: Check out [Schema Review Best Practices](docs/schema-review.md) for advanced configurations + +Need help? Open a discussion in the [Agentic Workflows community](https://github.com/githubnext/gh-aw/discussions). +``` + +### Complete Template Example + +Here's how all 7 parts flow together: + +```markdown +🎉 Successfully created your PR schema review automation workflow! + +## What Was Created + +- `.github/workflows/pr-schema-reviewer.md` (145 lines) - Main workflow that reviews database schema changes +- `.github/workflows/pr-schema-reviewer.lock.yml` (342 lines) - Compiled GitHub Actions workflow + +## Quick Start + +Compile the workflow: +\`\`\`bash +gh aw compile .github/workflows/pr-schema-reviewer.md +\`\`\` + +Test it manually: +\`\`\`bash +gh aw run pr-schema-reviewer --pr 123 +\`\`\` + +## Key Features + +✅ Automatically triggered on database schema PR changes +✅ Validates migration safety (no destructive operations) +✅ Checks for proper indexing on new columns +✅ Verifies backward compatibility +✅ Comments detailed analysis directly on PR + +## Customization Options + +### Adjust Trigger Conditions +\`\`\`yaml +paths: + - 'db/migrations/**/*.sql' # Only migration files +\`\`\` + +### Configure Analysis Depth +\`\`\`yaml +env: + ANALYSIS_LEVEL: strict # Options: basic, standard, strict +\`\`\` + +## Pro Tips + +💡 **Test with a draft PR first**: Create a draft PR with a small schema change to verify the workflow behavior. + +💡 **Use descriptive migration names**: Helps the analysis provide better context. + +💡 **Monitor execution time**: Schema analysis can take 2-5 minutes for large changes. + +## Next Steps + +1. **Test the workflow**: Create a test PR with a small schema change +2. **Review the first analysis**: Check the quality and accuracy +3. **Customize for your database**: Adjust rules for PostgreSQL, MySQL, etc. +4. **Enable required status checks**: Add to branch protection once confident +``` + +### Real-World Examples + +The following examples demonstrate the 7-part structure in action, adapted from high-scoring workflow responses in agent persona exploration research: + +#### Example 1: Frontend Developer - Visual Regression Testing (Score: 4.8/5.0) + +```markdown +✨ Successfully created your visual regression testing workflow! + +## What Was Created + +- `.github/workflows/visual-regression-test.md` (167 lines) - Automated visual testing on component changes +- `.github/workflows/visual-regression-test.lock.yml` (389 lines) - Compiled GitHub Actions workflow +- `docs/visual-testing-guide.md` (92 lines) - Setup and customization guide + +## Quick Start + +Compile and test the workflow: +\`\`\`bash +# Compile the workflow +gh aw compile .github/workflows/visual-regression-test.md + +# Test with a PR that has component changes +gh aw run visual-regression-test --pr 456 + +# View the generated report +open artifacts/visual-regression-report.html +\`\`\` + +## Key Features + +✅ Automatically captures screenshots of changed components +✅ Compares against baseline images from main branch +✅ Generates visual diff reports with pixel-perfect comparison +✅ Posts summary directly on PR with image previews +✅ Supports multiple browsers (Chrome, Firefox, Safari) +✅ Configurable viewport sizes for responsive testing + +## Customization Options + +### Target Specific Components +\`\`\`yaml +# In frontmatter, specify component paths: +env: + COMPONENT_PATHS: 'src/components/Button,src/components/Modal' +\`\`\` + +### Adjust Diff Sensitivity +\`\`\`yaml +env: + DIFF_THRESHOLD: 0.1 # 0.0 (exact) to 1.0 (ignore all differences) +\`\`\` + +### Configure Viewports +\`\`\`yaml +env: + VIEWPORTS: 'mobile:375x667,tablet:768x1024,desktop:1920x1080' +\`\`\` + +## Pro Tips + +💡 **Update baselines carefully**: Run `gh aw run visual-regression-test --update-baseline` only when intentional visual changes are made. + +💡 **Test in draft mode first**: Enable `playwright.headed: true` to watch browser automation during initial setup. + +💡 **Manage large diffs**: For major redesigns, consider creating a new baseline branch to avoid overwhelming PR reviews. + +💡 **Optimize performance**: Use `playwright.parallel: true` to run multiple browser tests simultaneously. + +## Next Steps + +1. **Generate initial baselines**: Run the workflow on main branch to create reference images +2. **Test with a small change**: Make a minor component update to verify detection works +3. **Review the report format**: Ensure the visual diff format meets your team's needs +4. **Integrate with CI**: Add as required check for component-touching PRs +5. **Explore advanced features**: Check out [Visual Testing Best Practices](docs/visual-testing-guide.md) +``` + +#### Example 2: DevOps Engineer - Deployment Monitoring (Score: 4.6/5.0) + +```markdown +🚀 Successfully created your deployment monitoring and incident automation workflow! + +## What Was Created + +- `.github/workflows/deployment-monitor.md` (203 lines) - Monitors deployments and creates incidents +- `.github/workflows/deployment-monitor.lock.yml` (456 lines) - Compiled GitHub Actions workflow + +## Quick Start + +Deploy and monitor: +\`\`\`bash +# Compile the workflow +gh aw compile .github/workflows/deployment-monitor.md + +# The workflow automatically triggers on deployment events +# To test manually with a specific deployment: +gh aw run deployment-monitor --deployment-id 123456 + +# View recent monitoring results: +gh run list --workflow=deployment-monitor.lock.yml +\`\`\` + +## Key Features + +✅ Automatically monitors all production deployments +✅ Fetches and analyzes deployment logs in real-time +✅ Detects common failure patterns (OOM, timeouts, config errors) +✅ Creates incident issues with root cause analysis +✅ Includes relevant log excerpts and stack traces +✅ Tags appropriate teams based on error type +✅ Integrates with PagerDuty for critical failures + +## Customization Options + +### Configure Monitoring Duration +\`\`\`yaml +env: + MONITOR_DURATION: 300 # Seconds to monitor post-deployment (default: 300) +\`\`\` + +### Set Failure Detection Patterns +\`\`\`yaml +# Add custom error patterns in prompt: +"Watch for these critical patterns: +- Database connection failures +- Memory leaks (heap > 90%) +- API gateway 5xx errors" +\`\`\` + +### Customize Incident Routing +\`\`\`yaml +safe-outputs: + create_issue: + labels: ["incident", "production", "{{ error_type }}"] + assignees: ["@oncall-engineer"] +\`\`\` + +### Integrate External Services +\`\`\`yaml +tools: + web-fetch: + allowed-domains: ["api.pagerduty.com", "hooks.slack.com"] +\`\`\` + +## Pro Tips + +💡 **Set up log aggregation**: Ensure your deployment platform exposes logs via API for effective monitoring. + +💡 **Fine-tune detection thresholds**: Start with conservative settings and adjust based on false positive rates. + +💡 **Test with staging deploys first**: Use staging deployments to validate the workflow before production. + +💡 **Configure notification preferences**: Use GitHub Actions notifications to alert the team about new incidents immediately. + +💡 **Archive resolved incidents**: Create automation to close incident issues when deployments succeed after fixes. + +## Next Steps + +1. **Test with a staging deployment**: Verify monitoring works correctly in a non-production environment +2. **Configure team notifications**: Set up Slack/email alerts for critical incidents +3. **Establish runbook links**: Add links to relevant runbooks in incident templates +4. **Enable auto-rollback**: Integrate with deployment tools to trigger automatic rollbacks on critical failures +5. **Review incident history**: After a week, analyze patterns to improve detection rules +``` + +#### Example 3: QA Tester - Test Coverage Analysis (Score: 4.7/5.0) + +```markdown +✅ Successfully created your automated test coverage analysis workflow! + +## What Was Created + +- `.github/workflows/test-coverage-analyzer.md` (134 lines) - Analyzes test coverage changes in PRs +- `.github/workflows/test-coverage-analyzer.lock.yml` (298 lines) - Compiled GitHub Actions workflow + +## Quick Start + +Enable coverage analysis: +\`\`\`bash +# Compile the workflow +gh aw compile .github/workflows/test-coverage-analyzer.md + +# The workflow runs automatically on PRs +# To test manually: +gh aw run test-coverage-analyzer --pr 789 + +# View coverage report: +gh pr view 789 --comments +\`\`\` + +## Key Features + +✅ Calculates coverage delta between PR and main branch +✅ Identifies uncovered lines in new/modified code +✅ Generates coverage report with visual indicators +✅ Comments recommendations directly on PR +✅ Highlights critical paths that need test coverage +✅ Supports multiple test frameworks (Jest, pytest, Go test) + +## Customization Options + +### Set Coverage Thresholds +\`\`\`yaml +env: + MIN_COVERAGE_CHANGE: -2 # Fail if coverage drops by more than 2% + TARGET_COVERAGE: 80 # Overall target percentage +\`\`\` + +### Configure Framework +\`\`\`yaml +# Specify your test framework in frontmatter: +runtimes: + node: + version: "20" + packages: + - "jest" + - "@jest/coverage" +\`\`\` + +### Customize Report Format +\`\`\`yaml +env: + REPORT_FORMAT: detailed # Options: summary, detailed, critical-only +\`\`\` + +## Pro Tips + +💡 **Require coverage on new code only**: Focus on ensuring new code is well-tested rather than penalizing legacy code. + +💡 **Exempt generated files**: Configure `.coveragerc` or `jest.config.js` to exclude auto-generated code from coverage requirements. + +💡 **Balance coverage with quality**: 100% coverage doesn't guarantee quality tests. Focus on meaningful test scenarios. + +💡 **Use coverage trends**: Track coverage over time to identify areas that need attention. + +## Next Steps + +1. **Verify coverage tool integration**: Ensure your test runner generates coverage reports correctly +2. **Set appropriate thresholds**: Start lenient and tighten based on team capability +3. **Add coverage badge**: Display coverage percentage in README using shields.io +4. **Review first PR analysis**: Check that recommendations are helpful and accurate +5. **Train team on coverage best practices**: Share guidelines on writing meaningful tests + +Need help? Check out [Test Coverage Best Practices](docs/test-coverage-guide.md). +``` + +### Key Success Factors + +Based on analysis of high-scoring workflow responses: + +1. **100% adoption of copy-paste ready commands**: Every successful workflow includes immediately executable commands +2. **Clear value proposition**: Key features section makes benefits immediately obvious +3. **Progressive disclosure**: Structure moves from quick wins (Quick Start) to advanced usage (Customization) +4. **Contextual emoji usage**: Emojis enhance readability without being excessive (1-2 per section max) +5. **Actionable pro tips**: Tips address real pain points discovered during testing +6. **Logical next steps**: Progression from testing to production deployment feels natural + +### When to Deviate from the Structure + +This structure works best for: +- Workflow creation responses +- Feature implementation announcements +- Automation setup guides + +Consider adapting or simplifying for: +- Simple bug fixes (may only need parts 1, 2, and 7) +- Documentation updates (may skip parts 3 and 4) +- Quick responses to clarification questions (success announcement and next steps only) + +The key is maintaining the spirit of clear communication while adapting to context. + +--- + ## Code Organization Patterns ### Recommended Patterns @@ -725,4 +1276,4 @@ For detailed specifications, see individual files in `specs/`: --- -**Last Updated**: 2026-01-28 +**Last Updated**: 2026-01-29