# Self-Improvement Mandate

> **Generated by**: @hawkinside_out/workflow-agent v{{VERSION}}  
> **Project**: {{PROJECT_NAME}}  
> **Last Updated**: {{DATE}}

This document defines the **mandatory** self-improvement and evolution rules for {{PROJECT_NAME}}.

---

## 🎯 Mandatory Rule: Continuous Improvement Tracking

### When This Applies

ANY time a developer, AI agent, or team member receives an "ask" or suggestion to improve the workflow, this process MUST be followed:

1. **Document the Request**
   - Create a new file in `.workflow/improvements/YYYY-MM-DD-<id>.md`
   - Use the template below
   - Timestamp: ISO 8601 format
   - Status: `proposed` (initial), `accepted`, `implemented`, `rejected`

2. **Categorize the Suggestion**
   - **validation**: Branch/commit/PR validation rules
   - **scopes**: Scope definitions, scope organization
   - **documentation**: Guideline updates, clarity improvements
   - **performance**: Speed, efficiency, workflow optimization
   - **security**: Security concerns, sensitive data handling
   - **ux**: Developer experience, CLI usability, IDE integration

3. **Prioritize Impact**
   - **critical**: Blocking issue, security vulnerability, data loss risk
   - **high**: Significant pain point affecting daily work
   - **medium**: Noticeable improvement but not urgent
   - **low**: Nice-to-have, minor enhancement

4. **Generate Implementation Plan**
   - Use the implementation plan template from `AGENT_EDITING_INSTRUCTIONS.md`
   - Include affected files, testing requirements, rollback plan
   - Estimate effort and impact

### Improvement Suggestion Template

\`\`\`markdown

# Improvement Suggestion

**ID**: <unique-id>
**Date**: <ISO-8601-timestamp>
**Status**: proposed | accepted | implemented | rejected
**Category**: validation | scopes | documentation | performance | security | ux
**Priority**: critical | high | medium | low
**Reporter**: <name-or-github-handle>

## Problem/Opportunity

<Clear description of what needs improvement and why>

## Proposed Solution

<Specific, actionable suggestion for improvement>

## Impact Analysis

- **Who is affected**: <developers, teams, CI/CD, etc.>
- **Frequency**: <how often is this encountered?>
- **Current workaround**: <how do people handle this now?>
- **Benefit if implemented**: <concrete improvements expected>

## Implementation Plan

### Changes Required

- [ ] File/component to modify — `path/to/file.ts`
- [ ] Update documentation — `docs/section.md`
- [ ] Add tests — `tests/improvement.test.ts`

### Testing

- [ ] Unit tests added
- [ ] Integration tests added
- [ ] Manual testing completed

### Rollback Plan

<How to undo this change if it causes issues>

## Notes

<Additional context, related issues, alternative approaches>

---

_To submit this improvement to the workflow-agent community:_
\`\`\`bash
workflow suggest "$(cat .workflow/improvements/YYYY-MM-DD-<id>.md)"
\`\`\`
\`\`\`

---

## 💡 Proactive Suggestion Rule

### Automatic Analysis Points

The workflow system MUST proactively analyze usage patterns and offer suggestions during these commands:

1. **`workflow validate`** - After validation errors
   - Detect repeated validation failures
   - Suggest scope aliases for common typos
   - Recommend adding frequently-used but unlisted scopes

2. **`workflow sync`** - When syncing team config
   - Compare local vs remote scope usage
   - Suggest consolidating duplicate/overlapping scopes
   - Recommend preset upgrades if available

3. **`workflow doctor`** - Health check analysis
   - Analyze git history for patterns (scope usage frequency, branch naming consistency)
   - Detect unused scopes (defined but never used in past 90 days)
   - Identify scope fragmentation (similar scopes that could merge)
   - Check for validation rule mismatches (rules too strict/loose based on failure rate)

### Suggestion Output Format

\`\`\`
💡 Workflow Optimization Suggestion

[CATEGORY: <category>] [PRIORITY: <priority>]

<One-line summary of the issue>

Details:
• <Specific observation or pattern detected>
• <Impact or frequency data>
• <Concrete example from git history>

Recommendation:
<Actionable suggestion with exact command or config change>

To apply automatically:
workflow apply-suggestion <id>

To provide feedback:
workflow suggest "Alternative approach: ..."
\`\`\`

### Pattern Detection Examples

**Example 1: Common Typo**

```
💡 Workflow Optimization Suggestion

[CATEGORY: validation] [PRIORITY: medium]

Detected 12 validation failures for scope 'task' (should be 'tasks')

Details:
  • 12 failed commits over past 30 days
  • All from 'tasks' scope being typed as 'task'
  • Affects 3 different team members

Recommendation:
  Add scope alias: 'task' → 'tasks' in workflow.config.ts

  aliases: {
    'task': 'tasks',
    'ui-component': 'ui'
  }

To apply automatically:
  workflow config add-alias task tasks
```

**Example 2: Scope Consolidation**

```
💡 Workflow Optimization Suggestion

[CATEGORY: scopes] [PRIORITY: low]

Both 'api' and 'backend' scopes exist but serve similar purposes

Details:
  • 'api' used in 45 commits (68%)
  • 'backend' used in 21 commits (32%)
  • Descriptions overlap: "Server actions, API patterns, data fetching"

Recommendation:
  Consolidate into single 'api' scope:
  1. Update 'api' scope description to be comprehensive
  2. Remove 'backend' scope
  3. Update CHANGELOG with migration note

To discuss with team:
  workflow suggest "Should we keep both api and backend scopes separate?"
```

---

## 📊 Evolution Tracking

### Changelog Requirements

ALL implemented improvements MUST be documented in `WORKFLOW_CHANGELOG.md` with:

- **Date**: When improvement was implemented
- **Version**: Semantic version bump (if using workflow-agent package)
- **Category**: Same as suggestion category
- **Summary**: One-line description
- **Rationale**: Why this improvement was made
- **Migration**: Any breaking changes or required actions
- **Reporter**: Who suggested the improvement (credit!)

### Changelog Template

\`\`\`markdown

## {{VERSION}} - {{DATE}}

### {{CATEGORY}} Improvements

**<One-line summary>**

- **Rationale**: <Why this was needed>
- **Changes**: <What changed>
- **Migration**: <How to adapt (if breaking)>
- **Reporter**: @<github-handle>
- **Impact**: <Who benefits and how>

\`\`\`

---

## 🔄 Workflow Agent Integration

If using `@hawkinside_out/workflow-agent` package, improvements are:

1. **Submitted** to central registry at `workflow-improvements.dev`
2. **Moderated** using trust scores and content filtering
3. **Voted** on by the community (upvote/downvote)
4. **Prioritized** by AI analysis (impact score calculation)
5. **Implemented** in future package releases
6. **Synced** back to your project via `workflow sync`

### Opting In to Community Improvements

Edit `workflow.config.ts`:

\`\`\`typescript
export default {
projectName: '{{PROJECT_NAME}}',
scopes: [...],

// Enable community improvement syncing
syncRemote: 'https://workflow-improvements.dev/registry',
analytics: {
enabled: true,
shareAnonymous: true, // Help improve the tool!
},
};
\`\`\`

---

## ✅ Pre-Commit Checklist Addition

Before EVERY commit touching workflow configuration, verify:

- [ ] **Improvement Documented**: If changing workflow rules, is there a corresponding improvement suggestion file?
- [ ] **Changelog Updated**: Is WORKFLOW_CHANGELOG.md updated with the change?
- [ ] **Team Notified**: For breaking changes, has the team been notified via Slack/Discord?
- [ ] **Migration Guide**: For breaking changes, is there a clear migration path documented?

---

## 🚫 Prohibited Actions

- ❌ Changing workflow rules without documenting rationale in improvement suggestion
- ❌ Ignoring repeated validation failures without investigating root cause
- ❌ Rejecting community improvement suggestions without feedback/rationale
- ❌ Making breaking changes to scope definitions without team discussion
- ❌ Bypassing validation in "strict" mode without documenting exception reason

---

## 🎓 Philosophy

> "A workflow that doesn't evolve is a workflow that dies."

The goal is **continuous improvement** driven by:

1. **Real usage data** - What actually happens in practice
2. **Developer feedback** - Pain points from the team
3. **Community wisdom** - Insights from other projects
4. **Automated analysis** - Pattern detection by AI

Every suggestion makes the workflow better for everyone. Your feedback matters!

---

_Generated by @hawkinside_out/workflow-agent - a self-evolving workflow management system_  
_Learn more: https://workflow.dev/docs/self-improvement_