diff --git a/.claude/commands/pongogo-add-work-log-entry.md b/.claude/commands/pongogo-add-work-log-entry.md deleted file mode 100644 index 3355fe1b..00000000 --- a/.claude/commands/pongogo-add-work-log-entry.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -description: Create work log entry on demand ---- - -# Pongogo Work Log - -Add a structured entry to the project work log. - -## Usage - -``` -/pongogo-add-work-log-entry # Interactive mode -/pongogo-add-work-log-entry completed the API refactor # Quick entry with context -``` - -## Entry Types - -| Type | Use When | -|------|----------| -| Session Start | Beginning work | -| Decision | Key choice made | -| Blocker | Obstacle encountered/resolved | -| Completion | Task/Epic done | -| Learning | Pattern or insight discovered | -| Session End | Progress summary | - -## Execution - -**Execute silently and display only the formatted output.** - -1. **Parse input** - Infer type from text or ask -2. **Gather details** - Get evidence, context, rationale -3. **Generate entry** - Use appropriate template -4. **Add to work log** - Insert at top of today's section -5. **Commit** - Stage and commit with descriptive message - -## Output - -Show only: -- Entry preview -- Confirmation of addition -- Commit status - ---- - -**Location**: `wiki/Work-Log-YYYY-MM.md` diff --git a/.claude/commands/pongogo-complete-issue.md b/.claude/commands/pongogo-complete-issue.md deleted file mode 100644 index a6b15c60..00000000 --- a/.claude/commands/pongogo-complete-issue.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -description: Run completion checklist on demand ---- - -# Pongogo Done - -Run the issue completion checklist to ensure proper closure. - -## Usage - -``` -/pongogo-complete-issue # Current issue context -/pongogo-complete-issue #123 # Specific issue number -``` - -## Execution - -Execute the completion process, surfacing only items needing attention. - -### Phase 1: In Progress -> Ready for Review - -1. **Deliverables** - Verify all acceptance criteria met -2. **Status Indicators** - All checkboxes marked -3. **Documentation** - Docs updated as needed -4. **Atomicity** - No deferred/blocked criteria -5. **Learning Loop** - Work log + learning execution -6. **Cross-Issue Impacts** - Update unblocked issues -7. **Completion Comment** - Summary added to issue -8. **Status Transition** - Move to "Ready for Review" - -### Phase 2: User Review - -9. **Approval** - Wait for user confirmation - -### Phase 3: Closure - -10. **Final Comment** - Note approval -11. **Close Issue** - Change status -12. **Project Board** - Move to "Done" -13. **Milestone** - Update checklist if applicable - -## Output - -``` -## Completion Checklist: #[number] - -### Items Needing Attention -- [ ] [Item description] - -### Actions Taken -- [Action 1] - -### Next Step -[What happens next] -``` - -If all pass: -``` -All items complete. Ready for your approval to close. -``` diff --git a/.claude/commands/pongogo-conduct-retro.md b/.claude/commands/pongogo-conduct-retro.md deleted file mode 100644 index 4ba45e6c..00000000 --- a/.claude/commands/pongogo-conduct-retro.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -description: Conduct learning loop on demand ---- - -# Pongogo Retrospective - -Run a structured learning loop to capture insights from completed work. - -## Usage - -``` -/pongogo-conduct-retro # Interactive mode -/pongogo-conduct-retro task # Task-level (5-10 min) -/pongogo-conduct-retro epic # Epic-level (30-60 min) -/pongogo-conduct-retro milestone # Milestone-level (2-3 hours) -``` - -## Execution - -**Execute silently and display only the formatted output.** - -Conduct a learning loop with the following phases: - -### Phase 1: ANALYZE -- What was accomplished? -- What worked well? (with evidence) -- What could be improved? (with evidence) -- Patterns observed (3+ occurrences = validated) - -### Phase 2: EXTRACT -- Check existing potential improvements for validation evidence -- Extract new opportunities (process, platform, knowledge) -- Apply 3+ occurrence threshold - -### Phase 3: CODIFY -- Implement validated improvements NOW -- Update instruction files, templates, Pattern Library -- Commit changes - -### Phase 4: DOCUMENT -- Task -> Work log entry -- Epic -> Retrospective entry in wiki -- Milestone -> Full retrospective document - -## Output - -Show only: -- Key insights discovered -- Improvements implemented -- Documentation created -- Commits made - ---- - -**Scope Guidance**: -- Task: Tactical (this task only) -- Epic: Domain patterns (3+ tasks) -- Milestone: Strategic (5+ epics) diff --git a/.claude/commands/pongogo-config.md b/.claude/commands/pongogo-config.md deleted file mode 100644 index 29fbbf38..00000000 --- a/.claude/commands/pongogo-config.md +++ /dev/null @@ -1,153 +0,0 @@ -# Pongogo Configuration - -View and edit Pongogo preferences for trigger behaviors and communication style. - -## Usage - -### View All Preferences - -``` -/pongogo-config -``` - -Shows current preference settings for all triggers and communication options. - -### Set Behavior Preference - -``` -/pongogo-config -``` - -Set how Pongogo handles a specific trigger: -- `auto` - Execute automatically -- `ask` - Prompt before action -- `skip` - Don't execute or mention - -**Examples**: -``` -/pongogo-config work_log auto -/pongogo-config retro ask -/pongogo-config issue_closure skip -``` - -### Available Triggers - -| Trigger | Description | -|---------|-------------| -| `work_log` | Work log entry on task completion | -| `retro` | Retrospective on task/epic completion | -| `pi_threshold` | PI system threshold prompts | -| `issue_commencement` | Issue start checklist | -| `issue_closure` | Issue completion checklist | -| `rca` | Root cause analysis on incidents | -| `decision_capture` | Capture key decisions | - -### Set Communication Preference - -``` -/pongogo-config communication -``` - -**Examples**: -``` -/pongogo-config communication verbosity concise -/pongogo-config communication tone casual -/pongogo-config communication acronyms false -``` - -### Reset Preferences - -``` -/pongogo-config reset -``` - -Clears all learned preferences, returning to defaults. - -``` -/pongogo-config reset -``` - -Reset a specific trigger to unlearned state. - ---- - -## Execution - -When this command is invoked: - -1. **Parse arguments** to determine action (view, set, reset) - -2. **Read current preferences** from `.pongogo/preferences.yaml` - -3. **For view**: Display current settings in a formatted table - -4. **For set**: - - Update the specified preference - - Save to `.pongogo/preferences.yaml` - - Confirm the change - -5. **For reset**: - - Clear specified preferences (or all) - - Save to `.pongogo/preferences.yaml` - - Confirm the reset - ---- - -## Output Format - -### View All - -```markdown -## Pongogo Preferences - -### Behavior Modes - -| Trigger | Mode | Learned | -|---------|------|---------| -| work_log | auto | 2025-12-20 | -| retro | ask | 2025-12-20 | -| pi_threshold | (not set) | - | -| issue_closure | auto | 2025-12-19 | - -### Communication - -| Setting | Value | -|---------|-------| -| Verbosity | balanced | -| Tone | professional | -| Acronyms | true | -| Emojis | false | - -### Committed Approaches - -| Problem Type | Technique | Uses | -|--------------|-----------|------| -| Root Cause Analysis | 5 Whys | 4 | -``` - -### Set Confirmation - -```markdown -Updated preference: -- **work_log**: ask → auto - -This will take effect immediately. -``` - -### Reset Confirmation - -```markdown -Reset preferences: -- work_log: cleared (was: auto) -- retro: cleared (was: ask) - -Pongogo will ask about these behaviors on next occurrence. -``` - ---- - -## Related - -- Design doc: `docs/design/preferences-system.md` -- Foundational instruction: `knowledge/instructions/_pongogo_core/_pongogo_collaboration.instructions.md` -- Preferences file: `.pongogo/preferences.yaml` diff --git a/.claude/commands/pongogo-contact.md b/.claude/commands/pongogo-contact.md deleted file mode 100644 index 4795c742..00000000 --- a/.claude/commands/pongogo-contact.md +++ /dev/null @@ -1,194 +0,0 @@ ---- -description: Contact Pongogo support with diagnostic info ---- - -# Pongogo Contact - -Get help from Pongogo support with pre-filled diagnostic information. - -## Usage - -``` -/pongogo-contact # General inquiry -/pongogo-contact issue # Report a problem (includes diagnostics) -/pongogo-contact feature # Request a feature -/pongogo-contact feedback # General feedback -``` - -## Execution - -### Step 1: Determine Contact Type - -Based on argument or ask user: - -| Type | Subject Prefix | Include Diagnostics | -|------|----------------|---------------------| -| `issue` | [Issue] | Yes - full diagnostics | -| `feature` | [Feature Request] | No | -| `feedback` | [Feedback] | No | -| (none) | [Inquiry] | Optional | - -### Step 2: Gather Information - -**For issue reports**, run diagnostics silently: - -```bash -# Get OS and architecture -OS=$(uname -s -m) - -# Get Docker version -DOCKER=$(docker --version 2>/dev/null | head -1 || echo "not installed") - -# Get Pongogo version (from config or container) -VERSION=$(grep -m1 "version:" .pongogo/config.yaml 2>/dev/null || echo "unknown") - -# Count instructions -INSTRUCTIONS=$(find .pongogo/instructions -name "*.md" 2>/dev/null | wc -l | tr -d ' ') - -# Container status -CONTAINER=$(docker ps --filter "ancestor=pongogo.azurecr.io/pongogo" --format "{{.Status}}" 2>/dev/null | head -1 || echo "not running") -``` - -### Step 3: Generate Email Link - -Build mailto URL with pre-filled content: - -**For issue reports**: -``` -Subject: [Issue] Brief description of problem - -Body: -## Issue Description - -[User describes issue here] - -## Steps to Reproduce - -1. -2. -3. - -## Expected Behavior - - - -## Actual Behavior - - - ---- -## Diagnostic Info (auto-generated) - -- OS: {OS} -- Docker: {DOCKER} -- Pongogo Version: {VERSION} -- Instructions: {INSTRUCTIONS} files -- Container: {CONTAINER} -- Config: .pongogo/ exists: yes/no -- MCP Config: .mcp.json exists: yes/no -``` - -**For feature requests**: -``` -Subject: [Feature Request] Brief description - -Body: -## Feature Description - -[Describe the feature you'd like] - -## Use Case - -[Why do you need this feature?] - -## Proposed Solution (optional) - -[Any ideas for how this could work?] -``` - -**For feedback**: -``` -Subject: [Feedback] Brief description - -Body: -## Feedback - -[Your feedback here] - -## Context (optional) - -[How are you using Pongogo?] -``` - -### Step 4: Present to User - -Show the pre-filled content and provide the mailto link: - -```markdown -## Contact Pongogo Support - -I've prepared a support email for you. Here's what will be sent: - ---- - -**To**: support@pongogo.com -**Subject**: [Issue] - -**Body**: -[Show the pre-filled body content] - ---- - -### Send Options - -1. **Click to open email client**: - [Open Email](mailto:support@pongogo.com?subject=...) - -2. **Copy and paste** (if mailto doesn't work): - - Email: support@pongogo.com - - Subject: [copy from above] - - Body: [copy from above] - ---- - -**Edit the placeholders** in brackets before sending! -``` - -### Mailto URL Encoding - -Properly encode the mailto URL: - -```python -import urllib.parse - -subject = "[Issue] Brief description" -body = """## Issue Description - -[Describe your issue here] - ---- -## Diagnostic Info -- OS: macOS arm64 -- Docker: Docker version 24.0.7 -""" - -mailto = f"mailto:support@pongogo.com?subject={urllib.parse.quote(subject)}&body={urllib.parse.quote(body)}" -``` - -### Privacy Note - -For issue reports, remind user: - -``` -**Privacy**: The diagnostic info above contains only: -- System info (OS, Docker version) -- File counts and paths -- Container status - -It does NOT include: -- File contents -- Personal data -- API keys or secrets - -You can remove any info you prefer not to share before sending. -``` diff --git a/.claude/commands/pongogo-diagnose.md b/.claude/commands/pongogo-diagnose.md deleted file mode 100644 index 11662b4a..00000000 --- a/.claude/commands/pongogo-diagnose.md +++ /dev/null @@ -1,249 +0,0 @@ ---- -description: Run comprehensive diagnostics for troubleshooting ---- - -# Pongogo Diagnose - -Run comprehensive diagnostics to verify Pongogo installation and generate a support bundle. - -## Usage - -``` -/pongogo-diagnose # Full diagnostics -/pongogo-diagnose --brief # Quick check only -``` - -## Execution - -**IMPORTANT: Run all diagnostic checks QUIETLY and display ONLY the final formatted diagnostic report.** - -- Do NOT show intermediate output, progress messages, or thinking aloud -- Do NOT display individual tool call results to the user -- Suppress all user-facing messaging during data gathering -- Execute each check silently, then aggregate results into the final report -- The user should see ONLY the formatted "## Pongogo Diagnostic Report" output below - -**CRITICAL: Use MCP tools directly - do NOT parse cached files** - -- Call MCP tools (e.g., `route_instructions()`, `get_health_status()`) and use the response directly -- Do NOT use `jq`, `cat`, or bash to read files from `.claude/projects/*/tool-results/` -- Do NOT try to parse cached MCP tool result files - they may be in unexpected formats -- Extract values directly from the MCP tool response object (e.g., `response.count`, `response.guidance_action`) - -Run all diagnostic checks and generate a formatted report. This report can be shared with support. - -### Diagnostic Checks - -#### 1. Environment Info -Gather system context (safe to share, no secrets): - -```bash -# OS and architecture -uname -s -m - -# Docker version -docker --version 2>/dev/null || echo "Docker not found" -``` - -#### 2. Configuration Validation - -Check `.pongogo/` directory: -- [ ] `.pongogo/config.yaml` exists and is valid YAML -- [ ] `.pongogo/instructions/` directory exists -- [ ] Count instruction files: `find .pongogo/instructions -name "*.md" | wc -l` -- [ ] Count categories: `ls -d .pongogo/instructions/*/ | wc -l` - -Check `.mcp.json`: -- [ ] File exists at project root -- [ ] Contains `pongogo-knowledge` server entry -- [ ] Docker command path is valid - -#### 3. MCP Server Connection & Health - -Use MCP tools to verify connection and get comprehensive health status: - -**Get comprehensive health status** (recommended): -- Call `get_health_status()` via MCP -- This returns all component statuses in one call: - - `overall`: "healthy" | "degraded" | "unhealthy" - - `container`: Container status - - `database`: Events database health - - `events`: Event capture activity - - `config`: Configuration validity - -**Get routing engine version (MCP server)**: -- Call `get_routing_info()` via MCP -- Extract `engine` from response (e.g., "durian-0.6.5") -- Extract `preceptor_version` from response (e.g., "0.1.0") -- This is the version running in the Docker container - -**Get routing engine version (CLI/pongogo wrapper)**: -- For container-based installations (standard): Run via Bash: `pongogo version --engine 2>/dev/null || echo "unknown"` -- Fallback for pip installations: `python -c "from mcp_server.pongogo_router import DURIAN_VERSION; print(DURIAN_VERSION)" 2>/dev/null` -- This is the version used by the CLI wrapper -- **Compare CLI vs MCP versions** - they should match -- If versions differ, it indicates the Docker container is stale or the pip package needs updating - -**Get pongogo package version and check for updates**: -- Call `check_for_updates()` via MCP -- Extract `display_version`, `current_version`, and `latest_version` from response -- Use `display_version` for user-facing version display (formatted with channel) -- Note if `update_available` is true - -**Test routing**: -- [ ] Call `route_instructions` with test query "how do I commit code?" and `diagnostic_mode=True` -- [ ] Verify returns > 0 results -- [ ] Record response time -- Note: `diagnostic_mode=True` prevents test queries from polluting event history - -#### 4. Event History - -Check routing event capture health using `get_routing_event_stats()` MCP tool: - -- [ ] Call `get_routing_event_stats()` via MCP -- [ ] Check `status` field: "active", "empty", or "missing" -- [ ] Note `total_count` for total events captured -- [ ] Note `last_event` timestamp and calculate relative time -- [ ] Note `last_24h_count` for recent activity - -**Status Interpretation**: -- **active**: Database exists with events - healthy state -- **empty**: Database exists but no events yet - recently initialized -- **missing**: No database file - `pongogo init` may not have been run - -#### 5. Routing Validation - -Test routing with known queries that should return results. -**IMPORTANT**: Use `diagnostic_mode=True` for all test queries to exclude them from event history. - -| Test Query | Expected Category | Pass/Fail | -|------------|-------------------|-----------| -| "how do I commit code?" | software_engineering | | - -Call: `route_instructions("how do I commit code?", diagnostic_mode=True)` - -#### 6. Guidance Detection - -Test that user guidance is properly detected and `guidance_action` is emitted. - -**Test query**: "Always double-check your work" - -- [ ] Call `route_instructions` with the test query and `diagnostic_mode=True` -- [ ] Check if `guidance_action` is present in response -- [ ] Check if `routing_analysis.guidance_pre_check` is `true` -- [ ] Note the signals detected - -**Expected result**: -- `guidance_action.action` = "log_user_guidance" -- `guidance_action.parameters.guidance_type` = "explicit" -- `guidance_action.signals` contains pattern match - -**If guidance_action is missing**: -- Check router version is `durian-0.6.4` or later -- Check feature flags: `guidance_pre_check: true`, `guidance_action: true` -- Check lexicon DB is loaded (look for "Lexicon DB loaded" in server logs) - -#### 7. Network Connectivity (if MCP connection fails) - -```bash -# Can reach container registry (run on HOST via Bash tool) -curl -s -o /dev/null -w "%{http_code}" https://pongogo.azurecr.io/v2/ 2>/dev/null -``` - -### Output Format - -Generate a copyable diagnostic report: - -```markdown -## Pongogo Diagnostic Report - -**Generated**: [timestamp] -**Pongogo Version**: [display_version from check_for_updates] -**Latest Version**: [latest_version from check_for_updates] [⚠️ Update available if update_available=true] -**Routing Engine (MCP)**: [from get_routing_info MCP tool, e.g., durian-0.6.5] -**Routing Engine (CLI)**: [from `pongogo version --engine`, e.g., durian-0.6.5] [⚠️ VERSION MISMATCH if different from MCP] -**Preceptor**: [preceptor_version from get_routing_info response] - -### Environment -- **OS**: [uname output] -- **Docker**: [version or "not found"] -- **Architecture**: [arm64/amd64] - -### Configuration -- **Config file**: ✅ Valid / ❌ Missing / ⚠️ Invalid -- **Instructions**: [instruction_count] files ([seeded_count] seeded + [core_count] core) -- **MCP config**: ✅ Valid / ❌ Missing / ⚠️ Invalid - -### MCP Server -- **Status**: ✅ Connected / ❌ Not connected -- **Version**: [display_version] → [latest_version] [✅ Up to date / ⚠️ Update available] - -### Event History -- **Status**: ✅ Active / ⚠️ Empty / ❌ Missing -- **Total Events**: [count] -- **Last Event**: [timestamp] ([relative time, e.g., "2 hours ago"]) -- **24h Activity**: [count] events - -### Routing Tests -| Query | Result | Time | -|-------|--------|------| -| commit code | ✅ 3 matches | 45ms | - -### Guidance Detection -- **Test Query**: "Always double-check your work" -- **guidance_action**: ✅ Present / ❌ Missing -- **Pre-check**: ✅ Enabled / ❌ Disabled -- **Signals**: [list of detected signals, e.g., "guideline_001"] - -### Overall Status -[✅ All systems operational / ⚠️ Issues detected / ❌ Critical failure] - -### Issues Found -[ONLY include this section if there ARE issues detected] -[If all checks passed, SKIP this section entirely - do not show "Issues Found" with "None detected"] -[List any actual problems detected here] - -### Recommended Actions -[ONLY include this section if there are issues to fix] -[Specific fix commands if issues found] -[If update_available: "Run `[upgrade_command]` then restart Claude Code"] -``` - -### Support Integration - -If issues are found, offer support options: - -``` -Issues detected. To get help: - -1. Run `/pongogo-contact issue` to generate a support email with diagnostics - -2. Or email directly: [support@pongogo.com](mailto:support@pongogo.com?subject=%5BIssue%5D%20Pongogo%20Diagnostic%20Failure&body=Please%20paste%20the%20diagnostic%20report%20above%20and%20describe%20your%20issue.) -``` - -### Quick Fixes Reference - -| Issue | Fix | -|-------|-----| -| MCP not connected | Restart Claude Code, allow MCP server when prompted | -| Router version mismatch | Restart Claude Code to reload MCP server with correct container version | -| Image not found | `pongogo upgrade` or `docker pull pongogo.azurecr.io/pongogo:stable` | -| Config invalid | `pongogo init --force` | -| No instructions | `pongogo init` | -| Routing returns 0 | Check `.pongogo/instructions/` exists and has `.md` files | -| Event history missing | Database auto-creates on first route call | -| Event history empty | Normal for new installs; events captured on first route call | -| guidance_action missing | Requires durian-0.6.4+; check `guidance_pre_check` feature is enabled | -| Guidance not detected | Check lexicon.db is loaded; verify guideline patterns exist | - -**NOTE**: Pongogo runs via Claude Code's MCP infrastructure. Do NOT suggest `docker-compose` commands - they don't apply here. - -### Privacy Note - -The diagnostic report contains: -- ✅ System info (OS, Docker version) -- ✅ File counts and paths -- ✅ Routing test results -- ❌ NO file contents -- ❌ NO personal data -- ❌ NO API keys or secrets diff --git a/.claude/commands/pongogo-getting-started.md b/.claude/commands/pongogo-getting-started.md deleted file mode 100644 index 42b7dac9..00000000 --- a/.claude/commands/pongogo-getting-started.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -description: Interactive onboarding and command reference ---- - -# Pongogo Getting Started - -Interactive guide for new users and quick command reference. - -## Usage - -``` -/pongogo-getting-started # Full interactive guide -/pongogo-getting-started quick # Just show commands -``` - -## Execution - -**Execute checks silently and display only the formatted welcome and command reference.** - -### First-Time User Detection - -Check if this appears to be a new user: -- Does `.pongogo/` exist? If not, suggest `pongogo init` -- Has routing been tested? Check for recent successful routes - -### Interactive Welcome - -For new users, present this welcome: - -``` -## Welcome to Pongogo! 🎾 - -Pongogo is your AI knowledge routing system. It helps Claude find the right -guidance for your project automatically. - -### What Just Happened - -When you ran `pongogo init`, we: -1. Created `.pongogo/` with configuration and instruction files -2. Set up the MCP server connection in `.mcp.json` -3. Installed slash commands (like this one!) - -### How It Works - -As you work, Pongogo automatically routes relevant instructions to Claude: -- Ask about commits → gets git safety and commit format guidance -- Working on tests → gets testing standards -- Managing issues → gets GitHub workflow guidance - -You don't need to do anything - it happens automatically in the background. -``` - -### Quick Start Checklist - -Present interactive checklist: - -``` -### Quick Start Checklist - -Let's make sure everything is working: - -1. **Verify MCP Connection** - Run `/mcp` and look for `pongogo-knowledge` ✓ - -2. **Test Routing** - Ask me: "How should I format commit messages?" - (You should see relevant guidance appear) - -3. **Check Status** - Run `/pongogo-status` for system health - -All good? You're ready to go! Pongogo works in the background automatically. -``` - -### Command Reference - -Always show the command reference: - -``` -### Available Commands - -| Command | What It Does | -|---------|--------------| -| `/pongogo-status` | Quick health check - is everything working? | -| `/pongogo-diagnose` | Deep diagnostics - for troubleshooting | -| `/pongogo-contact` | Contact support with diagnostic info | -| `/pongogo-config` | Edit your preferences | -| `/pongogo-add-work-log-entry` | Create a work log entry | -| `/pongogo-conduct-retro` | Run a retrospective/learning loop | -| `/pongogo-complete-issue` | Completion checklist for finishing work | -| `/pongogo-perform-rca` | Root cause analysis wizard | -| `/pongogo-recent-progress` | Summary of recent accomplishments | -| `/pongogo-upgrade` | Update to latest Pongogo version | -| `/pongogo-getting-started` | This guide | - -### Tips - -- **Pongogo is automatic** - you don't need to invoke it manually -- **Instructions evolve** - they improve based on your project's patterns -- **Check status anytime** - `/pongogo-status` for quick health check -- **Problems?** - `/pongogo-diagnose` generates a support bundle -``` - -### Contextual Help - -If user asks about specific topic, provide targeted guidance: - -**If asked about routing**: -``` -### How Routing Works - -When you send a message, Pongogo analyzes it and finds relevant instructions: - -1. Your message: "How do I safely force push?" -2. Pongogo matches: git_safety.instructions.md, commit_format.instructions.md -3. Claude receives: Your message + relevant guidance - -This happens automatically - no action needed from you. -``` - -**If asked about instructions**: -``` -### Your Instruction Files - -Instructions live in `.pongogo/instructions/` organized by category: - -- `software_engineering/` - Coding standards, commit formats -- `safety_prevention/` - Git safety, validation patterns -- `project_management/` - Work logging, issue tracking -- `quality/` - Testing, PR workflows -- ... and more - -These are seeded defaults. Over time, you can customize them for your project. -``` - -**If asked about customization**: -``` -### Customizing Pongogo - -1. **Edit preferences**: `/pongogo-config` -2. **Modify instructions**: Edit files in `.pongogo/instructions/` -3. **Add project-specific guidance**: Create new `.md` files in instructions - -Pongogo learns from your project's wiki/ and docs/ folders too. -``` - -### Troubleshooting Quick Links - -``` -### Need Help? - -- **Something broken?** → `/pongogo-diagnose` -- **Not seeing routing?** → Check `/mcp` for connection -- **Want to reset?** → `pongogo init --force` -- **Contact support** → `/pongogo-contact` -- **Report an issue** → https://github.com/pongogo/pongogo/issues -- **Learn more** → https://pongogo.com -``` diff --git a/.claude/commands/pongogo-perform-rca.md b/.claude/commands/pongogo-perform-rca.md deleted file mode 100644 index 5e90b852..00000000 --- a/.claude/commands/pongogo-perform-rca.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -description: Start RCA wizard on demand ---- - -# Pongogo RCA - -Start a Root Cause Analysis wizard for incidents or failures. - -## Usage - -``` -/pongogo-perform-rca # Interactive mode -/pongogo-perform-rca deployment failed # With incident context -``` - -## Execution - -**Execute background checks silently - only show the wizard steps and formatted output.** - -Guide through systematic root cause analysis. - -### Step 1: Incident Summary -- What happened? -- When did it occur? -- What was the impact? -- How was it detected? - -### Step 2: Timeline Construction -- Build chronological sequence of events -- Identify key decision points -- Note what was known at each point - -### Step 3: Root Cause Analysis (5 Whys) -- Why did [symptom] occur? -- Why did [cause 1] happen? -- Continue until root cause identified -- Distinguish contributing factors from root cause - -### Step 4: Contributing Factors -- Process gaps -- Communication gaps -- Tooling gaps -- Knowledge gaps - -### Step 5: Corrective Actions -- Immediate fixes (already done) -- Short-term prevention (this week) -- Long-term prevention (process/tooling changes) - -### Step 6: Documentation -- Create RCA document in `docs/rca/` -- Add PI entries for validated patterns -- Update relevant instruction files - -## Output - -``` -## RCA: [Incident Title] - -**Root Cause**: [One sentence] - -**Contributing Factors**: -- [Factor 1] - -**Corrective Actions**: -- [x] [Immediate fix] -- [ ] [Short-term] - [owner/timeline] -- [ ] [Long-term] - [task created] - -**Documentation**: [links to created docs] -``` diff --git a/.claude/commands/pongogo-recent-progress.md b/.claude/commands/pongogo-recent-progress.md deleted file mode 100644 index 74dc9177..00000000 --- a/.claude/commands/pongogo-recent-progress.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -description: Project accomplishment summary ---- - -# Pongogo Recent Progress - -Generate a summary of recent project accomplishments. - -## Usage - -``` -/pongogo-recent-progress # Last 7 days -/pongogo-recent-progress 14 # Last 14 days -/pongogo-recent-progress month # Current month -``` - -## Execution - -Gather and summarize recent work silently, then display results. - -### Data Sources - -1. **GitHub Issues** - Recently closed issues in active milestones -2. **Work Log** - Entries from specified period -3. **Commits** - Commit history summary -4. **Wiki** - Recent wiki updates - -### Aggregation - -- Group by milestone/epic -- Highlight key deliverables -- Count metrics (issues closed, commits, etc.) -- Identify patterns in work type - -## Output - -``` -## Recent Progress: [Date Range] - -### Milestone: [Name] -**Progress**: X/Y issues (Z%) - -**Completed**: -- [Issue #] [Title] -- [Issue #] [Title] - -**Key Deliverables**: -- [Deliverable 1] -- [Deliverable 2] - -### Metrics -| Metric | Count | -|--------|-------| -| Issues Closed | X | -| Commits | Y | -| Work Log Entries | Z | - -### Highlights -- [Notable accomplishment 1] -- [Notable accomplishment 2] -``` - ---- - -**Tip**: Use before standup meetings or status updates. diff --git a/.claude/commands/pongogo-status.md b/.claude/commands/pongogo-status.md deleted file mode 100644 index 3a761da0..00000000 --- a/.claude/commands/pongogo-status.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -description: Show current state and server health ---- - -# Pongogo MCP Server Status - -Quick health check for Pongogo knowledge routing. - -## Instructions - -**NOTE**: Do NOT pre-check for MCP tool availability. Simply attempt to call the MCP tools -and report any errors that occur. The tools may be available even if not visible in the -tools list (e.g., in --print mode). - -Execute silently and display only the formatted output below. - -### Checks to Perform - -1. Read `.pongogo-mcp-state.json` for mode -2. (Local dev only) Check `docker ps --filter name=pongogo-` for container status - skip if not applicable -3. Call `get_routing_info` MCP tool to get engine version and instruction count -4. Call `route_instructions` with any test query - only need to know if it returns > 0 results -5. **Event Logging Check**: Call `get_routing_event_stats` MCP tool - - Returns `status` ("active", "empty", "missing"), `total_count`, `last_event` timestamp - - Active ✅: status is "active" and last_event is recent - - Stale ⚠️: status is "active" but last_event is older than 1 hour - - Failed ❌: status is "missing" or "empty", or tool call fails - - Do NOT use Bash/sqlite3 to query the database directly — use the MCP tool - -### Output Format - -``` -## Pongogo Status - -**Mode**: [ENABLED ✅ | DISABLED ⭕ | SIMULATE 🧪] -**Engine**: [engine version from get_routing_info] -**Preceptor**: [preceptor_version from get_routing_info] -**Instructions**: [instruction_count from get_routing_info] -**Routing**: [Working ✅ | Failed ❌] -**Event Logging**: [Active ✅ | Stale ⚠️ | Failed ❌] -``` - -If all pass, add: -``` -All systems operational. -``` - -If any fail, show the ❌ status and the relevant fix: - -- MCP tool call failed: Check that the MCP server is running and configured in `.mcp.json` -- Routing failed (0 results): Run `pongogo start` to restart, or check container logs with `docker logs pongogo-$(basename $PWD)` -- Event Logging stale/failed: Run `/mcp` to reconnect, then verify with `/pongogo-status` - -### Commands Reference - -Show only if user asks or if troubleshooting: -- `/pongogo-diagnose` - Deep diagnostics -- `/pongogo-getting-started` - Onboarding guide -- `/pongogo-upgrade` - Update to latest version diff --git a/.claude/commands/pongogo-upgrade.md b/.claude/commands/pongogo-upgrade.md deleted file mode 100644 index 7771b21a..00000000 --- a/.claude/commands/pongogo-upgrade.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -description: Upgrade Pongogo to latest version ---- - -# Pongogo Upgrade - -Upgrade Pongogo to the latest version. - -## Usage - -``` -/pongogo-upgrade -``` - -## Execution - -**Use the MCP tool to get upgrade instructions.** - -1. Call the `upgrade_pongogo()` MCP tool (from pongogo-knowledge server) -2. Display the `message` from the response -3. Show the `upgrade_command` for the user to copy - -## Output - -Display the result from the MCP tool: - -``` -## Pongogo Upgrade - -**Current Version**: [current_version from response] - -**Upgrade Command**: -```bash -[upgrade_command from response] -``` - -**After running the command**: -1. Exit Claude Code -2. Re-enter Claude Code -3. Run `/mcp` to verify Pongogo is connected -``` - -If the MCP tool fails, suggest: -``` -Could not get upgrade info. Try manually: - -```bash -docker pull pongogo.azurecr.io/pongogo:stable -``` - -Then restart Claude Code. -``` diff --git a/.gitignore b/.gitignore index 400fa098..f1ed78da 100644 --- a/.gitignore +++ b/.gitignore @@ -33,3 +33,12 @@ scripts/fonts/ # OS files .DS_Store + +# Local agent/tool state — never publish +.claude/ +.pongogo/ +.superpowers/ +.mcp.json + +# Generated by scripts/render-email-header.ts (email.ts uses email-header.png) +email-header-b64.txt diff --git a/.mcp.json b/.mcp.json deleted file mode 100644 index b9fd14a3..00000000 --- a/.mcp.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "mcpServers": { - "pongogo-knowledge": { - "command": "pongogo-server" - } - } -} diff --git a/.pongogo/.gitignore b/.pongogo/.gitignore deleted file mode 100644 index 724ac170..00000000 --- a/.pongogo/.gitignore +++ /dev/null @@ -1,10 +0,0 @@ -# Pongogo local state (not version controlled) -# Main database with routing events, observations, artifacts -pongogo.db -pongogo.db-wal -pongogo.db-shm - -# PI system database (user guidance, improvements) -potential_improvements.db -potential_improvements.db-wal -potential_improvements.db-shm diff --git a/.pongogo/config.yaml b/.pongogo/config.yaml deleted file mode 100644 index 17b7d986..00000000 --- a/.pongogo/config.yaml +++ /dev/null @@ -1,30 +0,0 @@ -# Pongogo Configuration -# Generated by: pongogo init -# Documentation: https://github.com/pongogo/pongogo -# -# Categories: Enable/disable instruction categories -# Placeholders: Customize paths and identifiers for your project - -version: 1.0.0 -mode: native -container_name: null -categories: - _pongogo_core: true - software_engineering: true - project_management: true - agentic_workflows: true - architecture: true - quality: true - safety_prevention: true - testing: true - validation: true - devops: true - development: true - github_integration: true - trust_execution: true - documentation: true -placeholders: - wiki_path: wiki/ - docs_path: docs/ - owner_repo: '' - instructions_path: .pongogo/instructions/ diff --git a/.pongogo/instructions/agentic_workflows/agent_compliance_framework.instructions.md b/.pongogo/instructions/agentic_workflows/agent_compliance_framework.instructions.md deleted file mode 100644 index 9fa82ebf..00000000 --- a/.pongogo/instructions/agentic_workflows/agent_compliance_framework.instructions.md +++ /dev/null @@ -1,784 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Agent Compliance Framework" -description: "Meta-framework for agent compliance, governance, and operational transparency." -applies_to: - - "**/*" -domains: - - "agentic_workflows" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 1 - triggers: - keywords: - - compliance - - violation - - policy_violation - - shortcut - - transparency - - pre-execution_check - - enforcement_mechanism - - instruction_adherence - - unauthorized_substitution - - process_compliance - - GitHub_projects_pre-flight - - comment_gatekeeper - - internalization_pause - nlp: "Ensuring agents follow explicit instructions, policies, and processes without unauthorized shortcuts or substitutions" -evaluation: - success_signals: - - All 6 pre-execution checklist questions answered before work - - Enforcement mechanisms followed with documented evidence - - Zero undisclosed shortcuts or substitutions - - User confirms satisfaction with compliance and transparency - failure_signals: - - Work started without pre-execution checklist - - Enforcement evidence missing from output - - Hidden shortcuts discovered after execution - - User correction signals ignored ---- - - -# Agent Compliance Framework - -**Purpose**: Establish systematic compliance checks ensuring agents follow explicit user instructions, institutional policies, and established processes without unauthorized substitutions or shortcuts. - -**Philosophy**: Trust is built through compliance with explicit guidance - perceived "optimizations" that bypass instructions violate trust and degrade work quality. - ---- - -## When to Apply - -**CRITICAL**: Apply this framework BEFORE executing ANY work. - -This instruction applies when: - -- **Beginning any work session**: Validate understanding and compliance approach before first action -- **Receiving explicit user instructions**: Systematic process, step-by-step guidance, or specific requirements -- **Tempted to "optimize" or shortcut**: Perceived efficiency improvement that deviates from instructions -- **Encountering existing systematic work**: Analysis files, templates, established processes -- **Confused about requirements**: Ambiguous instructions, multiple interpretations, or unclear expectations -- **Creating GitHub Issues/PRs**: Before creating issues, validate templates, naming conventions, structure -- **Modifying files**: Before editing CLAUDE.md, instruction files, or any state-changing operation - -**Anti-Patterns to Prevent**: -- **Optimization Substitution**: Replacing explicit instructions with perceived improvements (see Pattern Library) -- **Transparency Failure**: Taking shortcuts without disclosure (see Pattern Library) -- **Execution Without Understanding**: Proceeding despite confusion about requirements - ---- - -## Quick Reference - -**Pre-Execution Compliance Checklist**: - -**Before starting work, answer these 6 critical questions**: - -1. **Instruction Adherence**: "Am I following explicit user instructions exactly?" - - ✅ YES → Proceed - - ❌ NO → Stop, ask for clarification or approval - -2. **Process Substitution Check**: "Have I substituted any 'optimizations' for explicit instructions?" - - ✅ NO substitutions → Proceed - - ❌ YES substitutions → Disclose and get approval first - -3. **Existing Work Trust**: "Am I using existing analysis/work rather than recreating?" - - ✅ YES using existing → Proceed - - ❌ NO recreating → Validate why recreation needed - -4. **Confusion Detection**: "Am I confused about any requirements?" - - ✅ NO confusion → Proceed - - ❌ YES confused → Use AskUserQuestion before executing - -5. **Shortcut Transparency**: "Am I taking any shortcuts?" - - ✅ NO shortcuts → Proceed - - ❌ YES shortcuts → Explicitly disclose and get approval - -6. **Policy Compliance**: "Does this approach comply with institutional policies (CLAUDE.md, instruction files)?" - - ✅ YES complies → Proceed - - ❌ NO violations → Adjust approach or seek approval - -**If ANY answer triggers STOP condition → Do not execute work until resolved** - ---- - -## Core Principles - -- **Explicit Instructions Are Binding**: User instructions take precedence over perceived "optimizations" or efficiency improvements - no substitutions without approval - -- **Transparency Builds Trust**: Disclose all shortcuts, assumptions, and deviations explicitly before executing - hidden changes destroy trust - -- **Ask When Confused**: Confusion indicates need for clarification, not permission to guess - use AskUserQuestion when uncertain about requirements - -- **Trust Existing Work**: When comprehensive systematic analysis exists, use it - don't recreate or shortcut around existing validated work - -- **Policy Compliance Is Mandatory**: Institutional policies (CLAUDE.md, instruction files, Pattern Library) are not suggestions - compliance required for all work - ---- - -## Step-by-Step Guidance - -### Phase 1: Pre-Work Validation (MANDATORY) - -1. **Read and Understand Instructions Completely** - - Read user's full request without sampling or skipping - - Identify explicit process requirements - - Note any sequential dependencies or phase ordering - - Expected outcome: Complete understanding of requested work - -2. **Execute Pre-Execution Checklist** - - Answer all 6 critical questions from Quick Reference - - Document any STOP conditions identified - - Resolve STOP conditions before proceeding - - Success indicator: All 6 questions pass without STOP triggers - -3. **Identify Existing Systematic Work** - - Check for analysis files, templates, established processes - - Verify existing work is current and applicable - - Plan to use existing work rather than recreating - - Common variation: If no existing work, document why creation needed - -4. **Validate Understanding With User** (if any uncertainty) - - Use AskUserQuestion to clarify ambiguous requirements - - Confirm multi-phase process sequencing - - Validate assumptions before acting on them - - Integration point: User approval enables Phase 2 execution - -### Phase 2: Compliant Execution - -5. **Follow Explicit Instructions Exactly** - - Execute steps in specified order - - Use specified tools and processes - - Respect phase boundaries and dependencies - - Rationale: Exact adherence prevents violations and rework - -6. **Use Institutional Resources** - - Use proper templates from docs/templates/ - - Query knowledge routing MCP for standards when creating issues - - Follow CLAUDE.md policies (naming validation, checkbox tracking, etc.) - - Success indicator: Templates used, standards validated, policies followed - -7. **Maintain Transparency Throughout** - - State any deviations from instructions explicitly - - Disclose shortcuts before taking them - - Communicate assumptions before acting on them - - Rationale: Continuous transparency enables user correction - -### Phase 3: Validation and Completion - -8. **Validate Work Against Requirements** - - Verify all explicit instructions followed - - Check compliance with institutional policies - - Confirm no undisclosed shortcuts taken - - Expected outcome: Work matches requirements exactly - -9. **Disclose Any Deviations** - - Explicitly state where deviated from instructions (if any) - - Explain rationale for deviations - - Seek user approval for deviations - - Success indicator: User satisfied with transparency - -10. **Document Compliance** - - Note what policies were followed - - Capture any clarifications received - - Record user approvals for deviations - - Integration point: Compliance documentation enables trust validation - ---- - -## ENFORCEMENT MECHANISMS (MANDATORY) - -**CRITICAL**: Having documentation is insufficient - agents must DEMONSTRATE compliance through evidence. - -**Key Insight**: "Available documentation ≠ Consulted documentation" - -The following enforcement mechanisms are MANDATORY for all process-related actions: - ---- - -### Mechanism 1: Pre-Execution Compliance Evidence - -**REQUIRED**: Before executing ANY process-related action, provide compliance evidence in output. - -**Evidence Format**: -```markdown -**Pre-Execution Compliance Evidence**: -- **Process**: [What I'm about to do] -- **Documentation Consulted**: [Instruction file path + key line numbers] -- **Key Requirement**: [Critical requirement from documentation] -- **Compliance Verification**: ✅ [How this action complies] -``` - -**Example**: -```markdown -**Pre-Execution Compliance Evidence**: -- **Process**: Creating project status update -- **Documentation Consulted**: knowledge/instructions/project_management/project_status_updates.instructions.md (lines 271-276) -- **Key Requirement**: Single paragraph, concise format with Priority Order -- **Compliance Verification**: ✅ Proposed update follows pattern: "Issue #123 (Title) now IN PROGRESS. Priority Order: #123 → #50. Rationale: [why]." -``` - -**When Required**: -- Moving GitHub Issue to "In Progress" or any status change -- Creating project status updates -- Creating/updating GitHub Issues -- Using comments on GitHub Issues -- Any action following documented procedure - -**Success Metric**: 100% of process actions include compliance evidence - ---- - -### Mechanism 2: Documentation Discovery via Routing System - -**REQUIRED**: Use knowledge routing system to find relevant documentation BEFORE acting. - -**Process**: -```bash -# Step 1: Query routing system -route_instructions( - message="[description of what I'm about to do]" -) - -# Step 2: Read ALL routed instructions -Read each instruction file returned - -# Step 3: Document consultation -State which instructions were consulted and key requirements extracted - -# Step 4: Execute per documented procedure -``` - -**Example**: -```markdown -Before moving Issue #123 to "In Progress": - -1. Queried: route_instructions(message="moving GitHub issue to in progress status") -2. Routed to: issue_commencement.instructions.md -3. Read: Complete checklist (lines 45-67) -4. Following: All checklist items before status change -``` - -**When Required**: -- Unfamiliar with documented procedure for an action -- First time performing specific process action -- Any uncertainty about correct procedure - -**Success Metric**: Zero violations of documented procedures that were available via routing - ---- - -### Mechanism 3: Comment Usage Gatekeeper - -**REQUIRED**: Before adding ANY GitHub comment, answer gatekeeper question. - -**Gatekeeper Question**: "Is this defining work to be done?" - -**Decision Tree**: -``` -Is this defining work to be done? -├─ YES → STOP - Must be Issue body or Sub-Issue, NEVER comment -│ - Task definitions -│ - Acceptance criteria changes -│ - Scope clarifications -│ - New deliverables -│ - Critical requirements -└─ NO → Comment is appropriate - - Progress updates - - Context about decisions - - Blockers encountered - - Questions for user - - Completion notifications - - Meta-comments ("updated issue body") -``` - -**When Required**: Before EVERY GitHub comment action - -**Success Metric**: Zero violations (work items in comments) - ---- - -### Mechanism 4: Internalization Pause - -**REQUIRED**: After creating or reviewing policy, pause before acting on related work. - -**Process**: -```markdown -1. Create/review policy document -2. Explicitly state: "This means I must [behavior change]" -3. Wait for next message before acting in covered area -4. Self-check before action: "Would this violate policy I just reviewed?" -``` - -**Example**: -```markdown -Just created policy document (Work Items Must Be Issues) - -**Internalization**: This means I must NEVER use GitHub comments for: -- Task definitions -- Acceptance criteria -- Scope changes -- New deliverables - -Before my next GitHub comment, I will verify it's NOT defining work. - -[PAUSE - wait for next message before any GitHub comment action] -``` - -**When Required**: -- After creating new policy document -- After creating new instruction file -- After reviewing policy due to violation - -**Success Metric**: Zero violations of self-created policies - ---- - -### Mechanism 5: Shortcut Cost Transparency - -**REQUIRED**: Before taking ANY shortcut, calculate and disclose true cost. - -**Cost Analysis Template**: -```markdown -**Proposed Shortcut**: [What I'm considering skipping] - -**Cost Analysis**: -- Time saved by shortcut: [X minutes] -- Risk of violation/rework: [probability %] -- Cost if rework needed: [Y minutes + trust impact] -- Expected cost: [Risk × Rework Cost] -- Net comparison: [Time saved vs Expected cost] - -**Decision**: [TAKE shortcut | DON'T TAKE - expected cost exceeds savings] -**User Approval**: [If taking shortcut, request explicit approval] -``` - -**Example**: -```markdown -**Proposed Shortcut**: Skip reading project_status_updates.instructions.md - -**Cost Analysis**: -- Time saved: ~2 minutes (reading time) -- Risk of wrong format: 80% (unfamiliar with pattern) -- Cost if wrong: ~15 minutes (rework + user intervention + trust reduction) -- Expected cost: 0.8 × 15 = 12 minutes -- Net comparison: Save 2 min vs Expect to lose 12 min - -**Decision**: DON'T TAKE - expected cost (12 min) >> savings (2 min) -**Action**: Reading documentation now -``` - -**When Required**: -- Tempted to skip documentation reading -- Considering using simplified version instead of comprehensive template -- Thinking "this is obvious, no need to verify" - -**Success Metric**: All shortcuts evaluated with cost analysis, shortcuts with negative expected value rejected - ---- - -### Mechanism 6: Issue Commencement Checklist (Mandatory) - -**REQUIRED**: Before moving ANY GitHub Issue to "In Progress", complete full checklist. - -**Process**: -1. Read: `docs/templates/issue_commencement_checklist.md` -2. Complete: Every checklist item -3. Document: Add comment to issue noting checklist completion -4. Only Then: Move to "In Progress" status - -**Checklist Items** (See full checklist file for complete list): -- [ ] Issue body review -- [ ] Acceptance criteria clarity -- [ ] Dependencies identified -- [ ] Blockers assessed -- [ ] Resources available -- [ ] Documentation consulted -- [ ] Approach validated - -**When Required**: Before EVERY status change to "In Progress" - -**Success Metric**: 100% of "In Progress" moves include completed checklist - ---- - -### Mechanism 7: File Path Conventions (Project-Specific) - -**REQUIRED**: Before creating files in temporary directories, verify project path conventions. - -**Critical Distinction**: -- **Project working files**: `tmp/` (project-relative directory) -- **System ephemeral files**: `/tmp/` (system temporary directory, cleared on reboot) - -**Pre-Execution Validation**: -```markdown -Before creating ANY temporary file: - -1. **Check file purpose**: - - Analysis, planning, working documents → `tmp/` (project) - - True ephemeral data (cleared on reboot OK) → `/tmp/` (system) - -2. **Verify path convention** (CLAUDE.md "Project-Specific Quirks"): - - ✅ CORRECT: `tmp/analysis_file.md` → `{project_root}/tmp/analysis_file.md` - - ❌ WRONG: `/tmp/analysis_file.md` → System temporary directory (data loss risk) - -3. **Use absolute path for clarity**: - - Preferred: `{project_root}/tmp/filename.md` - - Acceptable: `tmp/filename.md` (project-relative) - - NEVER: `/tmp/filename.md` (system directory) -``` - -**Common Mistakes**: -```markdown -❌ WRONG: Write("/tmp/task_validation.md", content) - - Files in system /tmp/ cleared on reboot (data loss risk) - - Inconsistent with project organization - - Cannot be version-controlled/git-ignored - -✅ CORRECT: Write("tmp/task_validation.md", content) - - Files preserved across reboots - - Project-relative, can be tracked - - Consistent with project standards -``` - -**Why This Matters**: -- **Data Loss Risk**: System `/tmp/` cleared on reboot → working files lost -- **Project Organization**: Project `tmp/` files can be version-controlled or intentionally git-ignored -- **Consistency**: Analysis files, migration plans, working documents belong in project structure - -**When Required**: -- Creating analysis documents -- Creating execution approach files -- Creating validation documents -- Creating any working file that should persist across sessions - -**Reference**: -- CLAUDE.md "Project-Specific Quirks > Temporary Files Directory" - -**Success Metric**: Zero files created in system `/tmp/` that should be in project `tmp/` - ---- - -### Mechanism 8: GitHub Projects Operations Pre-Flight (CRITICAL) - -**REQUIRED**: Before ANY GitHub Projects operation, execute mandatory pre-flight check with compliance evidence. - -**🛑 BLOCKING**: NO GitHub Projects operation may proceed without pre-flight completion. - -**Covered Operations**: -- Creating project status updates (`createProjectV2StatusUpdate`) -- Modifying project metadata (`updateProjectV2`) -- Updating custom fields on project items -- Adding/removing items from project -- ANY GraphQL mutation targeting `projectV2` or `projectsV2` - -**Mandatory 6-Step Pre-Flight**: -```markdown -1. **STOP**: Do not execute operation yet -2. **Query routing MCP**: route_instructions(message="[operation description]") -3. **Read ALL routed instructions**: Complete files, not summaries -4. **Extract key requirements**: Document critical constraints -5. **Provide compliance evidence**: In output BEFORE operation -6. **Execute per documentation**: Follow discovered procedure exactly -``` - -**Compliance Evidence Template**: -```markdown -**Pre-Flight Compliance Evidence**: -- **Operation**: [What I'm about to do] -- **Documentation Consulted**: [File paths + line numbers] -- **Key Requirements**: [Critical constraints extracted] -- **Compliance Verification**: ✅ [How this complies] - -**Pre-Flight Status**: ✅ COMPLETE - Proceeding with operation -``` - -**Example** (Status Update Creation): -```markdown -**Pre-Flight Compliance Evidence**: -- **Operation**: Creating project status update for Issue #123 move to In Progress -- **Documentation Consulted**: - - project_operations_preflight.instructions.md (complete file) - - project_status_updates.instructions.md (lines 22-38, 75-140) -- **Key Requirements**: - - Mutation: createProjectV2StatusUpdate (NOT updateProjectV2) - - Body: "Issue #123 now IN PROGRESS. Priority Order: ... Rationale: ..." - - Status: ON_TRACK -- **Compliance Verification**: ✅ Using correct mutation, following format - -**Pre-Flight Status**: ✅ COMPLETE - Proceeding with GraphQL mutation -``` - -**Why This Matters**: -- **Root Cause Prevention**: Used `updateProjectV2` instead of `createProjectV2StatusUpdate` -- **Prevention**: Mandatory evidence PROVES consultation occurred - -**Anti-Patterns Prevented**: -- Instruction File Write-Only Syndrome -- Prevention Without Enforcement -- Assumption-Based Execution - -**Enforcement** (Three-Layer Validation): - -**Layer 1 - Routing Verification**: -- Compliance evidence MUST show routing results (UserPromptSubmit hook OR manual MCP query) -- MUST list routed instruction IDs with scores and ranks -- Example: "project_status_updates.instructions (score: 45, rank: #2)" - -**Layer 2 - Full File Reading** (CRITICAL - prevents excerpt-only failure): -- Evidence MUST prove full file reading, not just excerpts -- MUST show: "Read [file]: lines 1-[total] ([total] lines)" -- CANNOT show only 500-char excerpt content -- Validation: If evidence shows only excerpt-level detail → VIOLATION (files not fully read) - -**Layer 3 - Requirement Extraction**: -- Evidence MUST reference specific line numbers from full files -- Example: "From project_status_updates.instructions (lines 75-140): Use createProjectV2StatusUpdate, NOT updateProjectV2" -- CANNOT show generic requirements (proves files not analyzed) - -**When Required**: EVERY TIME before ANY GitHub Projects operation (no exceptions) - -**Reference**: [GitHub Projects Operations Pre-Flight](../project_management/project_operations_preflight.instructions.md) - Complete workflow - -**Success Metric**: Zero GitHub Projects violations, 100% pre-flight execution rate - ---- - -## Examples - -### Example 1: Systematic Migration Execution - -**Scenario**: User provides analysis file and says "slowly, methodically, and iteratively through [file]" - -**Correct Approach**: -```markdown -**Pre-Execution Check**: -1. Instruction adherence: User said "slowly, methodically, iteratively" → Will read analysis file line-by-line, no scripts -2. Process substitution: No - using specified process exactly -3. Existing work: Analysis file exists → Will use it, not recreate -4. Confusion: None - process is clear -5. Shortcuts: None planned -6. Policy compliance: Complete Context Principle applies → Will read full file - -**Execution**: -- Reading analysis file sequentially (File 1/70, File 2/70, etc.) -- Following identified actions for each file -- No extraction scripts or summaries -- Asking clarification if any file entry ambiguous - -**Outcome**: User satisfied with exact compliance -``` - -**Context**: When user provides existing systematic work and explicit process -**Expected Result**: 0% rework, user trust maintained - -### Example 2: Detecting and Handling Confusion - -**Scenario**: User mentions "bolstering" instruction files but agent unsure if this means adding content TO instruction files FROM CLAUDE.md or vice versa - -**Incorrect Approach** (Anti-Pattern): -```markdown -❌ Agent assumes "bolstering" means condensing CLAUDE.md and proceeds with wrong direction -❌ Agent executes work despite confusion -❌ Result: 100% rework required, multiple reverts -``` - -**Correct Approach**: -```markdown -**Pre-Execution Check**: -1. Instruction adherence: User said "bolster instruction files" → UNCLEAR direction -2. Confusion detected: YES - "bolster" could mean add TO or condense FROM -3. STOP CONDITION: Must use AskUserQuestion - -**Clarification**: -> I want to confirm my understanding before proceeding. When you say "bolster -> instruction files," do you mean: -> -> A) Add content TO instruction files FROM CLAUDE.md (migrate content out of CLAUDE.md) -> B) Condense CLAUDE.md and add pointers TO instruction files -> C) Something else? -> -> I want to ensure I execute in the correct direction. - -**After Clarification**: -User confirms A → Execute migration of content TO instruction files -**Outcome**: Correct execution, no rework needed -``` - -**Context**: When any ambiguity or confusion exists about requirements -**Trade-offs**: Takes 30 seconds to ask, saves hours of rework - -### Example 3: GitHub Issue Creation With Validation - -**Scenario**: Creating new GitHub Issues for migration work - -**Incorrect Approach** (Anti-Pattern): -```markdown -❌ Agent creates simplified issue descriptions without templates -❌ Agent doesn't validate naming conventions -❌ Agent skips querying routing MCP for standards -❌ Result: All issues deleted, process violated -``` - -**Correct Approach**: -```markdown -**Pre-Execution Check**: -1. Policy compliance: CLAUDE.md says "ALWAYS validate issue names before creating" -2. Template usage: Must use docs/templates/task_*.md -3. Naming validation: Must query routing MCP for standards - -**Execution**: -# Step 1: Query naming standards -- Use route_instructions(topic="naming") -- Verify format: [Type]-lowercase_with_underscores - -# Step 2: Use proper templates -- Read docs/templates/task_feature_template.md -- Fill in ALL sections completely -- No simplified versions - -# Step 3: Validate before creating -- Check issue name matches: [Task]-knowledge_synthesis_execution -- Verify all template sections complete -- Confirm with user if structure correct - -**Outcome**: Issues created correctly, no deletion needed -``` - -**Context**: When creating GitHub Issues or other platform objects -**Expected Result**: Proper structure, validated naming, no rework - ---- - -## Validation Checklist - -Before considering work complete, verify: - -- [ ] **Instruction Adherence**: All explicit user instructions followed exactly -- [ ] **No Unauthorized Substitutions**: No "optimizations" replaced explicit process without approval -- [ ] **Existing Work Used**: Used existing analysis/templates rather than recreating -- [ ] **Confusion Resolved**: All ambiguities clarified before execution (no assumptions) -- [ ] **Transparency Maintained**: All shortcuts/deviations disclosed and approved -- [ ] **Policy Compliance**: All institutional policies followed (CLAUDE.md, instruction files, Pattern Library) -- [ ] **Sequential Dependencies Respected**: Multi-phase processes executed in correct order -- [ ] **Templates Used Properly**: Comprehensive templates used, not simplified versions -- [ ] **User Satisfaction**: User confirms work meets requirements - ---- - -## Common Pitfalls - -### Pitfall 1: Optimization Substitution - -- ❌ **Problem**: Agent replaces explicit "slowly, methodically through file" with script creation for "efficiency" -- **Why it happens**: Agent prioritizes perceived efficiency over explicit guidance -- ✅ **Solution**: Follow explicit instructions exactly - if optimization desired, ask first: "May I create a script instead of manual review?" -- **Example**: User says "read analysis file" → Agent reads file (doesn't create extraction script) - -### Pitfall 2: Execution Despite Confusion - -- ❌ **Problem**: Agent proceeds with work while confused about requirements, making wrong assumptions -- **Why it happens**: Agent wants to "get started" instead of clarifying first -- ✅ **Solution**: Use AskUserQuestion whenever confused - clarification takes 30 seconds, rework takes hours -- **Example**: Unclear process direction → Ask for clarification before executing - -### Pitfall 3: Hidden Shortcuts - -- ❌ **Problem**: Agent takes shortcuts without disclosure, requiring user vigilance to detect -- **Why it happens**: Agent assumes shortcuts acceptable if unnoticed -- ✅ **Solution**: Explicitly disclose ALL shortcuts and deviations - transparency builds trust -- **Example**: "I'm tempted to skip template validation for speed - may I do so?" - -### Pitfall 4: Recreating Existing Work - -- ❌ **Problem**: Agent creates scripts/summaries when comprehensive analysis already exists -- **Why it happens**: Agent doesn't recognize existing work as authoritative -- ✅ **Solution**: Trust and use existing systematic work - validate it's current and use it -- **Example**: Analysis file exists → Use it directly (don't recreate) - -### Pitfall 5: Template Shortcuts - -- ❌ **Problem**: Agent uses simplified issue descriptions instead of comprehensive templates -- **Why it happens**: Full templates seem "heavy" compared to quick descriptions -- ✅ **Solution**: Always use comprehensive templates from docs/templates/ - structure prevents omissions -- **Example**: Creating GitHub Issue → Use full task_feature_template.md - ---- - -## Edge Cases - -### Edge Case 1: Conflicting Instructions - -**When**: User provides new instruction that conflicts with earlier guidance or institutional policy - -**Approach**: -1. Explicitly state the conflict detected -2. Ask user for clarification: "Earlier you said X, now you're saying Y. Which takes precedence?" -3. Document which instruction takes priority -4. Proceed with clarified priority - -**Example**: -```markdown -> I notice a potential conflict: -> - Earlier: "Use two-pass process (bolster then streamline)" -> - Now: "Condense CLAUDE.md in this batch" -> -> Should I: -> A) Continue two-pass process (complete bolstering first) -> B) Switch to condensing now (override two-pass) -> C) Something else? -``` - -### Edge Case 2: Emergency Situations - -**When**: Critical production issue requires immediate action - -**Approach**: -1. Still validate against compliance checklist (takes 30 seconds) -2. If shortcuts necessary, explicitly state: "Emergency situation - proposing shortcut X for speed, with understanding of risk Y" -3. Get explicit approval for shortcuts -4. Document shortcuts taken for post-incident review - -**Example**: Production down → Still disclose shortcuts, but expedited approval process acceptable - -### Edge Case 3: User Explicitly Requests Optimization - -**When**: User says "feel free to optimize this process" - -**Approach**: -1. Confirm optimization scope: "May I optimize by changing X and Y?" -2. Describe specific optimizations planned -3. Get approval for each optimization -4. Document approved optimizations - -**Example**: User grants optimization permission → Still disclose specific changes, ensure approval - ---- - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| User corrects approach multiple times | Agent substituting optimizations for explicit instructions | Execute Pre-Execution Checklist - follow instructions exactly | -| Work requires git restore / revert | Agent executed without validating understanding | Use AskUserQuestion when any confusion exists | -| User discovers undisclosed shortcuts | Agent taking shortcuts without transparency | Explicitly disclose ALL deviations and shortcuts | -| Same mistakes repeated across sessions | Agent not learning from violations | Read retrospectives, review anti-patterns in Pattern Library | -| User says "I lost confidence in the work" | Multiple violations, hidden shortcuts, wrong outcomes | Full reset - restart with Pre-Execution Checklist, explicit transparency | -| Issues created incorrectly | Skipping templates, validation, or naming standards | Use comprehensive templates, validate naming, query routing MCP | - ---- - -## Related Instructions - -- **See also**: [Trust-Based Task Execution](../trust_execution/trust_based_task_execution.instructions.md) - How to trust completed work and validation safeguards -- **See also**: [Validation-First Execution](../validation/validation_first_execution.instructions.md) - Systematic prevention through validation before execution -- **See also**: [Agentic Decision Making](agentic_decision_making.instructions.md) - When agents can make autonomous decisions vs when to ask - ---- - -**Success Criteria**: Work completed with zero policy violations, user expresses satisfaction with compliance and transparency - -**Confidence Check**: Before executing work, answer: "Have I completed the Pre-Execution Checklist and resolved all STOP conditions?" diff --git a/.pongogo/instructions/agentic_workflows/agent_environment_setup.instructions.md b/.pongogo/instructions/agentic_workflows/agent_environment_setup.instructions.md deleted file mode 100644 index 9c4fca1b..00000000 --- a/.pongogo/instructions/agentic_workflows/agent_environment_setup.instructions.md +++ /dev/null @@ -1,897 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Agent Environment Setup" -description: "Agent environment setup, initialization, and capability detection guidance." -applies_to: - - "**/*" -domains: - - "agentic_workflows" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 1 - triggers: - keywords: - - environment_setup - - zero-configuration - - docker_compose - - dev_container - - devcontainer - - structured_output - - machine-readable - - JSON_output - - graceful_failure - - health_check - - health_endpoint - - diagnostic - - diagnose - - npm_run - - sensible_defaults - - environment_validation - - bootstrap - - setup_script - - service_discovery - - pino - - structured_logging - - agent-friendly_error - - recovery_steps - nlp: "Setting up development environments that work automatically for AI agents with structured output and graceful failures" -evaluation: - success_signals: - - Zero-configuration bootstrap works (docker-compose up) - - All tools produce JSON output option - - Errors include actionable recovery steps - - Health check endpoints return structured status - - Diagnostic command available (npm run diagnose) - failure_signals: - - Manual configuration required before services start - - Tool output unstructured (human-readable only) - - Error messages lack recovery guidance - - Health checks missing or always failing - - No diagnostic capability available ---- - - -# Agent Environment Setup Standards - -**Purpose**: Establish development environment and tooling standards that enable zero-configuration agent bootstrap, structured output for parsing, and graceful failures with actionable recovery steps. - -**Philosophy**: Agents are first-class developers - environment setup must be automatic, tool output must be machine-readable, and failures must provide clear recovery paths. - ---- - -## When to Apply - -Use these standards when: - -- Setting up development containers or local development environments -- Creating scripts or automation tools for agent use -- Designing CI/CD workflows that agents will interact with -- Implementing configuration management for services -- Building tooling for routing service, audit service, or knowledge system -- Writing documentation that agents will consume to set up environments - ---- - -## Quick Reference - -**Most Common Patterns**: - -**1. Progressive Permission Request**: -- Start: Basic repository scan (read-only) -- Demonstrate: Show analysis and suggestions -- Request: "To auto-fix issues, grant write access to `src/`" -- Explain: "This enables automatic PR creation for validation fixes" - -**2. Service Discovery** (Docker Compose): -```yaml -services: - routing-service: - environment: - KNOWLEDGE_SERVICE_URL: http://knowledge-service:3000 -``` - -**3. Machine-Readable Tool Output** (JSON): -```bash -# Bad: Human-friendly output -echo "Service started successfully" - -# Good: Machine-parseable JSON -echo '{"status": "success", "service": "routing", "port": 3000}' | jq -``` - -**4. Automatic Dependency Detection**: -```bash -# Check required tools exist -for cmd in docker jq gh; do - command -v $cmd >/dev/null || echo "ERROR: $cmd not installed" -done -``` - -**5. Self-Healing Setup Script**: -```bash -if [ ! -f .env ]; then - echo "Creating .env from .env.example..." - cp .env.example .env -fi -``` - ---- - -## Core Principles - -- **Progressive Integration**: Start with minimal setup, demonstrate value, then request additional permissions/integrations as needed with clear benefit explanations -- **Structured Output**: All tools produce machine-readable output (JSON, YAML, parseable text) for programmatic consumption -- **Graceful Failures**: Errors include actionable recovery steps, not just error messages -- **Consistent Interfaces**: Standard file locations, naming conventions, and entry points across all services -- **Automatic Discovery**: Tools and configs live in predictable locations that agents can find without documentation - -## Step-by-Step Guidance - -### Step 1: Design Zero-Configuration Development Environment - -Create development environments that work immediately without manual configuration. - -1. **Use Docker Compose for Local Development**: - ```yaml - # docker-compose.yml - Agents can start entire stack with one command - version: '3.8' - services: - routing-service: - build: ./services/routing - environment: - - NODE_ENV=development - - DB_HOST=postgres - ports: - - "3001:3000" - depends_on: - - postgres - volumes: - - ./knowledge:/app/knowledge:ro # Auto-mount knowledge base - - audit-service: - build: ./services/audit - environment: - - NODE_ENV=development - - DB_HOST=postgres - ports: - - "3002:3000" - depends_on: - - postgres - - postgres: - image: postgres:15 - environment: - - POSTGRES_DB={database} - - POSTGRES_PASSWORD=devpass # Sensible default for dev - volumes: - - pgdata:/var/lib/postgresql/data - - volumes: - pgdata: - ``` - - Expected outcome: Agent runs `docker-compose up` and entire environment works - - Rationale: No manual database setup, service configuration, or dependency installation - -2. **Provide Sensible Defaults for All Settings**: - ```typescript - // config/defaults.ts - Every setting has a working default - export const defaultConfig = { - server: { - port: process.env.PORT || 3000, - host: process.env.HOST || '0.0.0.0' - }, - database: { - host: process.env.DB_HOST || 'localhost', - port: parseInt(process.env.DB_PORT || '5432'), - name: process.env.DB_NAME || '{database}', - user: process.env.DB_USER || '{database}', - password: process.env.DB_PASSWORD || 'devpass' - }, - knowledge: { - basePath: process.env.KNOWLEDGE_PATH || './knowledge', - instructionsPath: process.env.INSTRUCTIONS_PATH || './knowledge/instructions' - } - }; - ``` - - Success indicator: Service starts successfully with no env vars set - -3. **Implement Environment Validation with Clear Error Messages**: - ```typescript - // Validate on startup, provide actionable errors - export function validateEnvironment(): ValidationResult { - const errors: string[] = []; - - if (!fs.existsSync(config.knowledge.instructionsPath)) { - errors.push( - `Instructions path not found: ${config.knowledge.instructionsPath}\n` + - `Action: Run 'npm run setup' or set INSTRUCTIONS_PATH environment variable` - ); - } - - if (config.database.password === 'devpass' && config.server.env === 'production') { - errors.push( - `Default password detected in production\n` + - `Action: Set DB_PASSWORD environment variable to secure password` - ); - } - - return { - valid: errors.length === 0, - errors, - warnings: [] - }; - } - ``` - - Expected outcome: Clear, actionable error messages guide agent to resolution - - Integration point: Agents can parse structured error output - -### Step 2: Create Structured Output for All Tools - -Design tools to produce machine-readable output that agents can parse programmatically. - -1. **Use JSON for Programmatic Output**: - ```bash - #!/bin/bash - # scripts/validate-instructions.sh - Produces JSON output - - results=() - exit_code=0 - - for file in knowledge/instructions/**/*.instructions.md; do - if ! validate_frontmatter "$file"; then - results+=("{\"file\": \"$file\", \"status\": \"error\", \"message\": \"Invalid frontmatter\"}") - exit_code=1 - else - results+=("{\"file\": \"$file\", \"status\": \"ok\"}") - fi - done - - # Output valid JSON array - echo "[" - printf '%s\n' "${results[@]}" | paste -sd ',' - - echo "]" - - exit $exit_code - ``` - - Expected outcome: Agent parses JSON to understand validation results - -2. **Provide Human-Readable and Machine-Readable Modes**: - ```typescript - // CLI tools support both modes - import yargs from 'yargs'; - - const argv = yargs - .option('format', { - choices: ['human', 'json', 'yaml'], - default: 'human', - description: 'Output format' - }) - .parse(); - - if (argv.format === 'json') { - console.log(JSON.stringify(results, null, 2)); - } else if (argv.format === 'yaml') { - console.log(yaml.dump(results)); - } else { - // Human-readable table format - console.table(results); - } - ``` - - Success indicator: Agents use `--format json`, humans use default - -3. **Include Metadata in Output**: - ```json - { - "timestamp": "2025-10-27T12:00:00Z", - "command": "validate-instructions", - "version": "0.1.0", - "results": [ - { - "file": "task_creation_workflow.instructions.md", - "status": "ok", - "checks": ["frontmatter", "structure", "links"] - } - ], - "summary": { - "total": 8, - "passed": 8, - "failed": 0 - }, - "exit_code": 0 - } - ``` - - Rationale: Agents need context (timestamp, version) for decision-making - -### Step 3: Implement Graceful Failure with Recovery Steps - -Ensure all failures provide clear, actionable recovery instructions. - -1. **Structure Error Messages with Actions**: - ```typescript - export class AgentFriendlyError extends Error { - constructor( - message: string, - public action: string, - public context?: Record - ) { - super(message); - this.name = 'AgentFriendlyError'; - } - - toJSON() { - return { - error: this.message, - action: this.action, - context: this.context, - timestamp: new Date().toISOString() - }; - } - } - - // Usage - if (!instructionFile.exists) { - throw new AgentFriendlyError( - `Instruction file not found: ${filename}`, - `Create file at: ${expectedPath}\nOr check INSTRUCTIONS_PATH environment variable`, - { filename, expectedPath, currentPath: process.cwd() } - ); - } - ``` - - Expected outcome: Agents know exactly what to do to fix the error - -2. **Provide Diagnostic Commands**: - ```bash - # scripts/diagnose.sh - Helps agents troubleshoot - echo "=== Environment Diagnostics ===" - echo "" - - echo "Node version: $(node --version)" - echo "Docker version: $(docker --version)" - echo "Docker Compose version: $(docker-compose --version)" - echo "" - - echo "Knowledge base path: ${KNOWLEDGE_PATH:-./knowledge}" - if [ -d "${KNOWLEDGE_PATH:-./knowledge}" ]; then - echo "✓ Knowledge base found" - echo " Instruction files: $(find ${KNOWLEDGE_PATH:-./knowledge}/instructions -name '*.instructions.md' | wc -l)" - else - echo "✗ Knowledge base not found" - echo " Action: Run 'git submodule update --init' or set KNOWLEDGE_PATH" - fi - echo "" - - echo "Services status:" - docker-compose ps --format json | jq -r '.[] | " \(.Service): \(.State)"' - ``` - - Success indicator: Agents run diagnostic, understand environment state - -3. **Implement Automatic Retries with Backoff**: - ```typescript - async function withRetry( - fn: () => Promise, - options: { - maxRetries: number; - backoffMs: number; - onRetry?: (attempt: number, error: Error) => void; - } - ): Promise { - let lastError: Error; - - for (let attempt = 1; attempt <= options.maxRetries; attempt++) { - try { - return await fn(); - } catch (error) { - lastError = error as Error; - if (attempt < options.maxRetries) { - options.onRetry?.(attempt, error as Error); - await sleep(options.backoffMs * attempt); - } - } - } - - throw new AgentFriendlyError( - `Operation failed after ${options.maxRetries} attempts`, - `Check service health with: npm run diagnose\nReview logs: docker-compose logs`, - { lastError: lastError.message } - ); - } - ``` - - Integration point: Transient failures handled automatically, persistent failures surface with diagnostics - -### Step 4: Establish Consistent File Organization - -Use predictable locations and naming conventions that agents can discover. - -1. **Standard Directory Structure**: - ``` - {project}/ - ├── .devcontainer/ # Development container config - │ └── devcontainer.json - ├── .github/ - │ └── workflows/ # CI/CD workflows - │ ├── test.yml - │ └── deploy.yml - ├── knowledge/ # Knowledge base (git submodule) - │ └── instructions/ - ├── services/ # Microservices - │ ├── routing/ - │ ├── audit/ - │ └── knowledge/ - ├── scripts/ # Automation scripts - │ ├── setup.sh - │ ├── validate.sh - │ └── diagnose.sh - ├── docs/ # Documentation - │ ├── architecture/ - │ └── api/ - ├── docker-compose.yml # Local development - └── package.json # Root package config - ``` - - Expected outcome: Agents find tools and configs without documentation - -2. **Consistent Entry Points**: - ```json - { - "name": "{project}", - "scripts": { - "setup": "scripts/setup.sh", - "start": "docker-compose up", - "test": "scripts/test.sh", - "validate": "scripts/validate.sh", - "diagnose": "scripts/diagnose.sh", - "dev": "docker-compose up --watch", - "logs": "docker-compose logs -f" - } - } - ``` - - Rationale: Agents discover capabilities through `npm run` without docs - -3. **Self-Documenting Configuration**: - ```yaml - # .devcontainer/devcontainer.json - { - "name": "{Project} Development", - "dockerComposeFile": "../docker-compose.yml", - "service": "devcontainer", - "workspaceFolder": "/workspace", - - // Extensions agents benefit from - "customizations": { - "vscode": { - "extensions": [ - "dbaeumer.vscode-eslint", - "esbenp.prettier-vscode", - "GitHub.copilot" - ] - } - }, - - // Automatic setup on container creation - "postCreateCommand": "npm install && npm run setup", - - // Port forwarding for services - "forwardPorts": [3001, 3002, 5432], - - // Environment variables with documentation - "containerEnv": { - "NODE_ENV": "development", - "KNOWLEDGE_PATH": "/workspace/knowledge", - // Add service-specific vars here - } - } - ``` - - Success indicator: Dev container starts, runs setup, agent ready to work - -### Step 5: Create Comprehensive Logging and Diagnostics - -Implement logging that helps agents understand system state and troubleshoot issues. - -1. **Structured Logging**: - ```typescript - import pino from 'pino'; - - const logger = pino({ - level: process.env.LOG_LEVEL || 'info', - transport: { - target: 'pino-pretty', - options: { - colorize: process.env.NODE_ENV !== 'production' - } - } - }); - - // Usage produces parseable logs - logger.info({ - service: 'routing', - action: 'match_instructions', - context: 'task creation', - matches: 1, - confidence: 0.95, - durationMs: 12 - }, 'Instruction matching complete'); - - // Error logging with recovery info - logger.error({ - service: 'routing', - action: 'load_instruction', - file: 'missing.instructions.md', - error: 'FILE_NOT_FOUND', - recovery: 'Check KNOWLEDGE_PATH or create file' - }, 'Failed to load instruction file'); - ``` - - Expected outcome: Agents parse logs to understand system behavior - -2. **Health Check Endpoints**: - ```typescript - // services/routing/src/health.ts - app.get('/health', async (req, res) => { - const health = { - status: 'healthy', - timestamp: new Date().toISOString(), - service: 'routing', - version: process.env.VERSION || 'dev', - checks: { - database: await checkDatabase(), - knowledgeBase: await checkKnowledgeBase(), - dependencies: await checkDependencies() - } - }; - - const allHealthy = Object.values(health.checks).every(c => c.status === 'ok'); - res.status(allHealthy ? 200 : 503).json(health); - }); - - async function checkKnowledgeBase() { - try { - const instructionFiles = await listInstructionFiles(); - return { - status: 'ok', - instructionCount: instructionFiles.length, - lastScanned: new Date().toISOString() - }; - } catch (error) { - return { - status: 'error', - error: error.message, - action: 'Check KNOWLEDGE_PATH and file permissions' - }; - } - } - ``` - - Integration point: Agents query health endpoints to validate service readiness - -3. **Comprehensive Error Context**: - ```typescript - // Capture full context on errors - try { - const result = await routingService.match(request); - } catch (error) { - logger.error({ - service: 'routing', - operation: 'match_instructions', - request: { - context: request.context, - filePatterns: request.filePatterns - }, - environment: { - knowledgePath: config.knowledge.basePath, - nodeEnv: process.env.NODE_ENV - }, - error: { - message: error.message, - stack: error.stack, - name: error.name - }, - timestamp: new Date().toISOString() - }, 'Routing operation failed'); - throw error; - } - ``` - - Success indicator: Error logs contain all information needed for diagnosis - -## Examples - -### Example 1: Zero-Configuration Routing Service Setup - -**Context**: Agent needs to run routing service locally to test instruction matching - -**Scenario**: Agent clones repo and needs working environment immediately - -```bash -# Agent executes these commands, nothing else needed -git clone https://github.com/{owner}/{repo}.git -cd {project} -docker-compose up - -# Output shows services starting with defaults: -# ✓ routing-service started on port 3001 -# ✓ audit-service started on port 3002 -# ✓ postgres initialized with schema -# ✓ Knowledge base mounted from ./knowledge - -# Agent can immediately test -curl http://localhost:3001/health -# { -# "status": "healthy", -# "checks": { -# "database": {"status": "ok"}, -# "knowledgeBase": {"status": "ok", "instructionCount": 8} -# } -# } - -curl -X POST http://localhost:3001/api/route \ - -H "Content-Type: application/json" \ - -d '{"context": "task creation"}' -# { -# "matches": [{ -# "file": "task_creation_workflow.instructions.md", -# "confidence": 0.95, -# "reason": "Context match + priority P0" -# }] -# } -``` - -**Expected Result**: Working environment in under 2 minutes, zero manual configuration - -### Example 2: Structured Tool Output for Validation - -**Context**: Agent validates instruction files before committing changes - -**Scenario**: Agent runs validation script and needs to parse results programmatically - -```bash -# Agent runs validation with JSON output -npm run validate -- --format json > results.json - -# results.json contains structured output -cat results.json -``` - -```json -{ - "timestamp": "2025-10-27T12:00:00Z", - "command": "validate-instructions", - "version": "0.1.0", - "results": [ - { - "file": "task_creation_workflow.instructions.md", - "status": "ok", - "checks": { - "frontmatter": {"status": "ok", "fields": ["title", "description", "applies_to"]}, - "structure": {"status": "ok", "sections": ["When to Apply", "Core Principles", "Examples"]}, - "links": {"status": "ok", "broken": []} - } - }, - { - "file": "broken_example.instructions.md", - "status": "error", - "checks": { - "frontmatter": {"status": "error", "message": "Missing 'priority' field"}, - "structure": {"status": "ok"}, - "links": {"status": "error", "broken": ["./missing_file.md"]} - }, - "action": "Add 'priority' field to frontmatter\nFix broken link: ./missing_file.md" - } - ], - "summary": { - "total": 8, - "passed": 7, - "failed": 1 - }, - "exit_code": 1 -} -``` - -**Agent Decision Logic**: -```typescript -const results = JSON.parse(fs.readFileSync('results.json', 'utf-8')); - -if (results.exit_code !== 0) { - const failures = results.results.filter(r => r.status === 'error'); - for (const failure of failures) { - console.log(`Fix required for ${failure.file}:`); - console.log(failure.action); - } - process.exit(1); -} -``` - -**Expected Result**: Agent parses structured output, understands failures, knows exact fixes needed - -**Trade-offs**: More complex output format, but enables programmatic decision-making - -### Example 3: Graceful Failure with Recovery Steps - -**Context**: Routing service can't find knowledge base on startup - -**Scenario**: Environment misconfiguration, agent needs clear recovery path - -```typescript -// Service startup validation -const startupValidation = validateEnvironment(); - -if (!startupValidation.valid) { - logger.error({ - service: 'routing', - phase: 'startup', - validation: startupValidation - }, 'Environment validation failed'); - - // Output structured error for agents - console.error(JSON.stringify({ - error: 'ENVIRONMENT_VALIDATION_FAILED', - details: startupValidation.errors, - actions: startupValidation.errors.map(e => e.action), - diagnostic_command: 'npm run diagnose', - timestamp: new Date().toISOString() - }, null, 2)); - - process.exit(1); -} - -// Output when validation fails: -{ - "error": "ENVIRONMENT_VALIDATION_FAILED", - "details": [ - "Instructions path not found: ./knowledge/instructions" - ], - "actions": [ - "Run 'npm run setup' to clone knowledge submodule", - "Or set INSTRUCTIONS_PATH environment variable to correct location", - "Or check that knowledge submodule is initialized: git submodule update --init" - ], - "diagnostic_command": "npm run diagnose", - "timestamp": "2025-10-27T12:00:00Z" -} -``` - -**Agent Recovery Process**: -```bash -# Agent sees error, executes suggested action -npm run setup - -# Or runs diagnostic for more info -npm run diagnose - -# Diagnostic output guides resolution: -# ✗ Knowledge base not found -# Current path: ./knowledge -# Expected: ./knowledge/instructions -# Action: git submodule update --init -# Or: export KNOWLEDGE_PATH=/path/to/knowledge -``` - -**Expected Result**: Agent resolves issue without human intervention using provided recovery steps - -## Validation Checklist - -Complete before marking agent environment setup as done: - -### Zero-Configuration Bootstrap -- [ ] Docker Compose brings up all services with no env vars required -- [ ] All services have sensible defaults for development -- [ ] Devcontainer/Codespace works immediately after creation -- [ ] Setup script automates any required initialization -- [ ] Health checks verify environment is ready - -### Structured Output -- [ ] All CLI tools support `--format json` option -- [ ] JSON output includes metadata (timestamp, version, exit_code) -- [ ] Error output includes structured recovery actions -- [ ] Logs use structured format (JSON, pino, etc.) -- [ ] Health endpoints return structured status - -### Graceful Failures -- [ ] All errors include actionable recovery steps -- [ ] Diagnostic command available (npm run diagnose) -- [ ] Retries implemented for transient failures -- [ ] Error messages include context (env vars, file paths, etc.) -- [ ] Exit codes follow conventions (0=success, 1=error, 2=misuse) - -### Consistent Interfaces -- [ ] Standard directory structure documented and followed -- [ ] Entry points accessible via npm scripts -- [ ] File locations predictable (configs in root, scripts in scripts/, etc.) -- [ ] Naming conventions consistent across services -- [ ] Documentation co-located with code - -## Common Pitfalls - -### Pitfall 1: Manual Configuration Required - -- ❌ **Problem**: Services require manual setup steps (database init, env vars, etc.) before working -- **Why it happens**: Assuming human-driven setup, not designing for automation -- ✅ **Solution**: Provide defaults for everything, automate initialization in docker-compose/devcontainer -- **Example**: Requiring agent to manually create `.env` file instead of providing defaults with override capability - -### Pitfall 2: Unstructured Tool Output - -- ❌ **Problem**: Tools output human-readable text that agents can't parse reliably -- **Why it happens**: Designing for human users, forgetting agent consumption -- ✅ **Solution**: Support both human and JSON output modes, default to human -- **Example**: Validation script outputs colored text instead of JSON with structured results - -### Pitfall 3: Cryptic Error Messages - -- ❌ **Problem**: Errors say "Failed to connect to database" without context or recovery steps -- **Why it happens**: Traditional error handling focused on describing problem, not solving it -- ✅ **Solution**: Include context (what, why, how to fix) in every error -- **Example**: "Database connection failed" vs "Database connection failed: postgres:5432 unreachable. Action: Check docker-compose ps, ensure postgres service is running" - -### Pitfall 4: Inconsistent File Locations - -- ❌ **Problem**: Configs scattered across repo, scripts in random locations, no conventions -- **Why it happens**: Organic growth without structure -- ✅ **Solution**: Establish directory structure, document conventions, enforce in CI -- **Example**: Scripts in `./bin/`, `./tools/`, `./.scripts/` instead of consistent `./scripts/` - -### Pitfall 5: Missing Diagnostics - -- ❌ **Problem**: When things fail, agent has no way to understand system state -- **Why it happens**: Assuming developers will just "figure it out" -- ✅ **Solution**: Provide diagnostic command that outputs comprehensive system state -- **Example**: Service fails to start with no logs vs detailed health check showing database unreachable, knowledge path not found - -## Edge Cases - -### Edge Case 1: Production vs Development Configuration - -**When**: Defaults work for development, but production needs different values - -**Approach**: -- Development defaults in code (safe, convenient) -- Production requires explicit environment variables -- Validate on startup: if NODE_ENV=production and using dev defaults, error -- Document production requirements in deployment guide - -**Example**: DB password defaults to "devpass" for local dev, but startup validation fails if production env detected - -### Edge Case 2: Platform-Specific Behavior - -**When**: Tool behaves differently on macOS, Linux, Windows - -**Approach**: -- Use Docker for consistency where possible -- Abstract platform differences behind npm scripts -- Document platform requirements clearly -- Provide platform-specific diagnostics - -**Example**: File path separators, line endings, Docker Desktop vs Docker Engine - handle transparently - -### Edge Case 3: Slow or Unreliable External Dependencies - -**When**: GitHub API rate limits, network timeouts, service unavailability - -**Approach**: -- Implement retries with exponential backoff -- Provide offline mode/mocks for development -- Cache responses when appropriate -- Clear error messages about external dependency failures - -**Example**: GitHub MCP integration times out - retry 3x, then fail with clear message about rate limiting - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| Service won't start | Missing environment configuration | Run `npm run diagnose`, check output for missing vars | -| Docker Compose fails | Port conflicts or resource limits | Check `docker ps` for conflicts, adjust ports in docker-compose.yml | -| Knowledge base not found | Git submodule not initialized | Run `git submodule update --init` or `npm run setup` | -| Tests fail in CI but pass locally | Environment differences | Use same Docker image locally and in CI, check for hardcoded paths | -| Tool output unreadable by agent | Human-readable format | Add `--format json` flag support to all tools | -| Health check always fails | Unrealistic timeout or missing dependency | Increase timeout, fix dependency, or remove check | - -## Related Instructions - -- **See also**: [agentic_decision_making.instructions.md](./agentic_decision_making.instructions.md) - How agents use environment setup for context-first decisions -- **Prerequisites**: [instruction_file_creation.instructions.md](../documentation/instruction_file_creation.instructions.md) - Creating discoverable instructions agents can find -- **See also**: [deterministic_validation_framework.instructions.md](../validation/deterministic_validation_framework.instructions.md) - Testing environment setup deterministically - ---- - -**Success Criteria**: Agents can clone repo, run `docker-compose up`, and have fully functional development environment within 2 minutes. All tools produce structured output agents can parse. All failures include actionable recovery steps. - -**Confidence Check**: Can an agent start working without reading documentation? Do tools produce JSON output for parsing? Do errors tell agents exactly what to do? diff --git a/.pongogo/instructions/agentic_workflows/agentic_decision_making.instructions.md b/.pongogo/instructions/agentic_workflows/agentic_decision_making.instructions.md deleted file mode 100644 index d9e516ac..00000000 --- a/.pongogo/instructions/agentic_workflows/agentic_decision_making.instructions.md +++ /dev/null @@ -1,551 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Agentic Decision Making" -description: "Framework for autonomous agent decision-making with appropriate escalation boundaries." -applies_to: - - "**/*" -domains: - - "agentic_workflows" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 1 - triggers: - keywords: - - decision_making - - context-first - - inference - - systematic_prevention - - verification_efficiency - - trust_completed_work - - urgency_signal - - process_compliance - - escalate_to_human - - conflicting_guidance - - script-first_thinking - - automation_vs_inference - - judgment - - knowledge_system_integration - - verification_budget - - redundant_verification - - point_solution - - problem_category - - situational_context - - established_patterns - nlp: "How agents make intelligent context-based decisions using inference patterns rather than automated rule-following" -evaluation: - success_signals: - - Decision rationale documented with context - - Inference used over automation for judgment calls - - Systematic prevention considered (category vs instance) - - Urgency signals trigger extra process, not bypass - failure_signals: - - Script-first thinking for judgment decisions - - Urgency causing process bypass - - Friction signals ignored - - Redundant verification despite efficiency protocols ---- - - -# Agentic Decision Making - -**Purpose**: Define how agents make intelligent context-based decisions versus automated rule-following through systematic inference patterns. - -**Philosophy**: Agents should infer correct actions from context and established patterns rather than relying on scripts to automate decision-making. - ---- - -## When to Apply - -Use this framework when: - -- Agents need to make decisions with incomplete information -- Multiple valid approaches exist requiring judgment -- Context determines the appropriate pattern to use -- Preventing entire categories of problems through systematic analysis -- Routing service needs to select appropriate knowledge and instructions - ---- - -## Quick Reference - -**Key Decision Criteria**: - -**1. Context-First Decision Flow**: -- Gather context → Identify patterns → Select approach → Validate → Execute - -**2. Inference vs Automation**: -- ❌ Automation: "Run script X when condition Y" -- ✅ Inference: "Given context Z, determine appropriate action from available patterns" - -**3. When to Escalate to Human**: -- Novel situation with no established patterns -- High-impact decision with significant unknowns -- Conflicting guidance from multiple sources -- Safety-critical operations (production deployments, data migrations) - -**4. Systematic Prevention Questions**: -- Can we prevent this entire category of problems? -- Does a framework/pattern already exist? -- Would solving this help with similar future situations? - -**5. Trust Completed Work**: -- Work marked "done" assumed complete unless evidence of failure -- Don't re-verify unless specific concern identified -- Focus on new work, not redundant checks - ---- - -## Core Principles - -- **Inference Over Automation**: Make intelligent decisions rather than automating decision-making away -- **Context-First Understanding**: Gather situational context before taking any action -- **Systematic Prevention**: Create frameworks that eliminate entire categories of problems, not individual instances -- **Knowledge System Integration**: Leverage existing knowledge systems rather than building new tools -- **Trust Completed Work**: Apply verification efficiency protocols to avoid redundant operations - -## Step-by-Step Guidance - -### 1. **Gather Situational Context** - - Discover current state: What is the actual system/project state? - - Clarify intent: What specific problem needs solving? - - Assess systematic prevention: Is this a one-time issue or broader problem category? - - Evaluate impact: What will change if I take this action? - - Expected outcome: Complete understanding of situation before acting - -### 2. **Query Established Patterns** - - Check knowledge base for relevant instruction files - - Review recent work logs for context and precedent - - Reference architecture documentation for constraints - - Apply existing decision frameworks rather than creating new scripts - - Expected outcome: Leverage proven patterns instead of reinventing solutions - -### 3. **Apply Inference Rules** - - Classify problem: Routine operation or exception requiring judgment? - - Select solution: What is simplest direct approach using existing tools? - - Detect redundancy: Have I already verified this information in current context? - - Apply verification efficiency: Check verification budget before re-reading files - - Document decision rationale: "Reading because..." or "Trusting because..." - - Expected outcome: Intelligent decision based on context, not automated response - -### 4. **Validate Decision Quality** - - Verify success of action taken - - Detect failures and apply recovery procedures - - Document decision patterns for future use - - Feed learnings back to knowledge system - - Expected outcome: Decision quality improves over time through learning - -## Examples - -### Example 1: Routing Service Decision Making - -Context: Agent receives request to implement authentication feature for an API service - -```yaml -# Agent inference process (NOT scripted automation) - -# Step 1: Situational Analysis -current_context: - - Target: API microservice authentication - - Scope: New feature implementation - - Complexity: Moderate (established patterns exist) - -# Step 2: Query Knowledge Base -relevant_instructions: - - security/authentication_patterns.instructions.md - - api_design/endpoint_standards.instructions.md - - trust_execution/feature_development.instructions.md - -# Step 3: Apply Inference -decision: - approach: "Use JWT authentication following established API patterns" - rationale: "Context indicates API service, existing JWT patterns apply" - validation: "Follow SC→AC→CV gates for bounded autonomy" - -# Step 4: Validate -outcome: - - Implementation follows established patterns - - No need to build new authentication framework - - Decision documented in work log -``` - -**Context**: Routing service selecting appropriate guidance without script-based automation -**Expected Result**: Agent makes intelligent decision based on context and available knowledge - -### Example 2: Systematic Prevention vs Point Solution - -Context: Agent encounters failing test due to missing environment variable - -```markdown -## ❌ WRONG: Point Solution (Script-First Thinking) -"I need to build a script to set this environment variable" - -Action: Write script to set variable -Result: One instance solved, pattern repeats elsewhere - -## ✅ CORRECT: Systematic Prevention (Inference Pattern) -"What systematic framework prevents this category of problems?" - -Analysis: -- Root cause: Environment configuration not validated at startup -- Pattern: All services need environment validation -- Solution: Create environment validation framework in agent_environment_setup - -Action: Add startup validation checking all required env vars -Result: Entire category of missing env var problems prevented -Documentation: Update agent_environment_setup.instructions.md -``` - -**Context**: Distinguishing between solving individual problems vs eliminating problem categories -**Expected Result**: Systematic prevention framework prevents future occurrences - -### Example 3: Verification Efficiency Application - -Context: Agent working on multi-session feature spanning 3 days - -```markdown -## Session 1: Initial Analysis -- Read architecture_doc.md (verification count: 1) -- Document: "Architecture follows microservices pattern with API gateway" - -## Session 2: Implementation Phase -Summary states: "architecture_doc.md verified 1x - microservices with gateway" -Decision: TRUST summary, DO NOT re-read architecture_doc.md -Rationale: No architecture changes, verification budget preserved - -## Session 3: Integration Testing -Summary states: "architecture_doc.md verified 1x - DO NOT re-verify" -Decision: TRUST directive, proceed with integration testing -Rationale: Verification efficiency protocol - avoid redundant operations -``` - -**Context**: Trust-based execution across sessions using verification efficiency protocols -**Expected Result**: Cognitive load reduced, verification budget preserved, faster execution - -## Validation Checklist - -Validate agent decision-making quality: - -- [ ] Situational context gathered before action -- [ ] Existing knowledge systems queried for patterns -- [ ] Inference rules applied based on context -- [ ] Systematic prevention considered (problem category vs instance) -- [ ] Verification efficiency protocols followed -- [ ] Decision rationale documented -- [ ] No script-first solutions for judgment-requiring decisions -- [ ] Knowledge system updated with new patterns discovered - -## Common Pitfalls - -### Pitfall 1: Script-First Thinking - -- ❌ **Problem**: "I need to build a script to handle this" -- **Why it happens**: Defaulting to automation instead of understanding -- ✅ **Solution**: Ask "What do I need to understand about this situation?" first -- **Example**: Building bulk update script without understanding current state → Gather context, apply targeted changes using existing tools - -### Pitfall 2: Automation Without Understanding - -- ❌ **Problem**: "Let me automate this bulk operation" -- **Why it happens**: Treating all problems as automation opportunities -- ✅ **Solution**: Understand each item individually, validate impact, apply targeted changes -- **Example**: Automating issue status updates without checking current priorities → Query current state, understand context, make informed decisions - -### Pitfall 3: Tool Building Over Knowledge Application - -- ❌ **Problem**: "I need better tools to handle this complexity" -- **Why it happens**: Assuming tools solve complexity that requires judgment -- ✅ **Solution**: Document decision patterns, establish inference rules, codify judgment criteria -- **Example**: Building custom analyzer instead of documenting analysis patterns → Capture decision framework in instruction files for agent inference - -### Pitfall 4: Redundant Verification - -- ❌ **Problem**: Re-reading files already verified in current context -- **Why it happens**: Not applying verification efficiency protocols -- ✅ **Solution**: Check verification count, trust documented state when budget reached -- **Example**: Reading same architecture doc 5 times in one session → Trust after verification #2, proceed with implementation - -## Edge Cases - -### Edge Case 1: Conflicting Context Signals - -**When**: Multiple sources provide different guidance for same situation -**Approach**: -- Apply priority hierarchy: P0 instructions override P2 instructions -- Check recency: More recent decisions supersede older ones -- Escalate ambiguity: Flag genuine conflicts for human resolution -- Document resolution: Update knowledge base with conflict resolution pattern - -**Example**: API design instruction conflicts with legacy compatibility requirement → Document exception, update routing service to handle legacy special case - -### Edge Case 2: No Established Pattern Exists - -**When**: Novel situation without precedent in knowledge base -**Approach**: -- Document decision rationale thoroughly -- Apply general principles from similar contexts -- Flag as new pattern discovery opportunity -- Update knowledge base after validation -- Request human review for high-impact decisions - -**Example**: New third-party integration without existing patterns → Document integration approach, validate, add to knowledge base as new pattern - -### Edge Case 3: Verification Budget Conflicts with Safety - -**When**: Verification efficiency suggests trusting, but changes indicate re-verification needed -**Approach**: -- Safety overrides efficiency when state changes detected -- Document why re-verification necessary -- Reset verification count for changed files -- Update efficiency protocols if pattern emerges - -**Example**: Architecture doc changed during session → Re-verify despite efficiency budget, document state change detection - ---- - -## Urgency Signals and Process Compliance - -**CRITICAL PATTERN**: When users signal urgency, INCREASE process vigilance, don't bypass process. - -### The Counter-Intuitive Principle - -**Common Mistake** (urgency bias): -``` -User urgency signal → Bypass process → Jump to implementation -"must-have", "critical", "now" → Code changes → Skip clarification/task creation -``` - -**Correct Response** (urgency → extra vigilance): -``` -User urgency signal → EXTRA process compliance → Clarify before acting -"must-have", "critical", "now" → Pause → Ask clarifying question → Proceed correctly -``` - -### Why Urgency INCREASES Process Need - -**Intuition**: "User said 'now', they want speed, skip process" -**Reality**: "User said 'critical', high stakes, GET IT RIGHT means ask questions" - -**Cost Analysis**: -- Quick clarification: 30 seconds (1 question) -- Wrong implementation: 20+ minutes (implement wrong approach + rework + retrospective) -- **Ratio**: 40:1 cost increase from skipping clarification - -### Urgency Signal Detection - -**Strong Language Signals** (PAUSE and ask): -- "must-have", "critical", "blocking" -- "definitely", "immediately", "now" -- "production", "risk", "noise" -- Problem framed as time-sensitive or blocking - -**User Options Presented** (ask which one): -- "might want to...", "unless...", "or..." -- "could create...", "if..." -- Multiple approaches mentioned without clear preference - -### Decision Framework - -**When urgency signals present**: - -**Step 1: Detect Signal** -- Strong language? ("must-have", "critical", "now") -- Risk framing? ("introducing noise", "production impact") -- Options presented? ("might want", "unless", "or") - -**Step 2: PAUSE (don't implement immediately)** -- Stop before starting code changes -- Recognize high-stakes decision -- Prepare clarifying question - -**Step 3: Ask Clarifying Question** -- "Should I [Option A] or [Option B]?" -- "Is this part of current work or separate scope?" -- "Do you want me to create task first, or consider this part of [current work]?" - -**Step 4: Wait for Answer** -- Don't assume user preference -- Don't default to most convenient interpretation -- Let user decide approach - -**Step 5: Proceed with Confirmed Approach** -- Follow user's stated preference -- Apply full process (task creation if requested) -- Implement correctly first time - -### Common Patterns - -**Pattern 1: "Now" Means Prioritize, Not Bypass** -``` -❌ User: "We need this now" - Agent: [Implements immediately without clarifying scope] - -✅ User: "We need this now" - Agent: "Should I create an Issue for this work, or is it part of current task?" - User: "Create separate issue" - Agent: [Creates issue, implements, completes properly] -``` - -**Pattern 2: Options = User Uncertainty** -``` -❌ User: "We might want to create a task, unless it's covered elsewhere" - Agent: [Assumes it's covered, implements without asking] - -✅ User: "We might want to create a task, unless it's covered elsewhere" - Agent: "This isn't in current scope. Should I create a new Issue?" - User: "Yes, create sub-issue under the parent task" - Agent: [Creates issue, proceeds correctly] -``` - -**Pattern 3: Capability Boundaries ≠ Technical Continuity** -``` -❌ Agent: "This feels like next step in code changes [continues coding]" - Reality: New capability, not enhancement - -✅ Agent: "This adds new capability (simulate mode). Should I create separate issue or include in current work?" - User: "Create sub-issue" - Agent: [Pauses, creates issue, proceeds] -``` - -### Anti-Pattern: Urgency Bias - -**What It Looks Like**: -- User uses strong language → Agent implements immediately -- User presents options → Agent picks one silently -- Technical changes feel continuous → Agent doesn't pause at conceptual boundaries - -**Why It's Wrong**: -- Urgent work has HIGHER cost of getting wrong (not lower) -- Process prevents expensive mistakes (not causes delay) -- Quick question << long rework - -**How to Fix**: -1. Add urgency detector: Strong language = PAUSE, not BYPASS -2. Add ambiguity detector: Options presented = ASK, not ASSUME -3. Add capability detector: New feature = scope check, not continuation - -### Success Metrics - -**Process Compliance**: -- Zero urgency-driven process bypasses -- 100% clarification when options presented -- All new capabilities get scope confirmation - -**Time Efficiency**: -- 30-second clarification prevents 20+ minute rework -- First-time correct > fast-but-wrong - ---- - -## Friction Signals and Recovery - -**CRITICAL PATTERN**: When users signal friction, PAUSE and RECOVER, don't continue current approach. - -### The Friction Detection Principle - -**Common Mistake** (friction blindness): -``` -Friction signal → Continue current approach → More friction -"wait, that's not" → Assume user is confirming → Build on wrong foundation -``` - -**Correct Response** (friction → recovery): -``` -Friction signal → STOP → Clarify → Recover with correct approach -"wait, that's not" → Pause → "What should I do differently?" → Proceed correctly -``` - -### Why Friction INCREASES Process Need - -Same principle as urgency signals: -- **Intuition**: "User seems frustrated, go faster to fix it" -- **Reality**: "User signaled problem, PAUSE to understand what's wrong" - -**Cost Analysis**: -- Quick clarification: 30 seconds (1 question) -- Continuing wrong direction: 20+ minutes (more friction + rework + trust damage) -- **Ratio**: 40:1 cost increase from ignoring friction - -### Friction Signal Detection - -**Strong Friction Signals** (STOP immediately): -- "wait, hold on" - User interrupting current action -- "that's not what I" - Direct contradiction of approach -- "you're skipping" - Missing expected step -- "yet another example of" - Repeated issue (pattern!) -- "i thought we" - Expectation mismatch - -**Soft Friction Signals** (proceed carefully, watch for escalation): -- "hmm, I was thinking" - Mild redirection -- "actually, could you" - Polite correction -- "sorry, I meant" - User self-correcting - -### Friction Recovery Protocol - -**Step 1: Acknowledge** -- "Let me pause here" -- "I see I may have misunderstood" - -**Step 2: Clarify** -- "What should I do differently?" -- "What was I missing?" - -**Step 3: Confirm Before Proceeding** -- "So you'd like me to [corrected approach]?" -- Wait for explicit confirmation - -**Step 4: Proceed with Corrected Understanding** -- Implement user's actual intent -- Note learning for future (potential pattern) - -### Common Friction Patterns - -| Friction Signal | What It Means | Correct Response | -|-----------------|---------------|------------------| -| "you're skipping X" | User expects step X | Ask what X should include | -| "wait, I wanted to review" | User wants approval gates | Pause, show work, get approval | -| "that's not what I meant" | Misunderstood requirements | Clarify exact expectation | -| "we already discussed this" | Repeated issue = pattern | Acknowledge, capture as learning | - -### Anti-Pattern: Friction Blindness - -**What It Looks Like**: -- User signals correction → Agent explains why current approach is good -- User shows frustration → Agent speeds up to "fix it faster" -- Soft correction → Agent continues assuming it's on track - -**Why It's Wrong**: -- Friction signals mean something is WRONG -- Explaining doesn't fix the wrong approach -- Speed amplifies the wrong direction - -**How to Fix**: -1. Add friction detector: Correction language = PAUSE -2. Override "helpful" instinct: Don't explain, ask -3. Trust user signals: They know what they want - ---- - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| Agent builds scripts for judgment tasks | Script-first thinking pattern | Apply inference framework, document decision patterns instead | -| Redundant verification operations | Verification efficiency protocols not applied | Check verification count, trust documented state, follow efficiency rules | -| Decision paralysis on routine operations | Over-analyzing simple problems | Classify problem type first, apply established patterns for routine operations | -| Inconsistent decisions across sessions | Not leveraging knowledge base | Query instruction files and work logs before deciding, document precedents | -| Systematic problems keep recurring | Point solutions instead of prevention | Analyze root cause, create framework eliminating problem category | - -## Related Instructions - -- **See also**: [trust_based_task_execution.instructions.md](../trust_execution/trust_based_task_execution.instructions.md) - Trust framework enabling efficient cross-phase decision-making -- **Prerequisites**: [agent_environment_setup.instructions.md](./agent_environment_setup.instructions.md) - Agent-first design principles for structured environments -- **Next steps**: [feature_development.instructions.md](../trust_execution/feature_development.instructions.md) - Practical application of autonomy ladder in feature work - ---- - -**Success Criteria**: Agents make context-based intelligent decisions using inference patterns rather than automated rule-following, systematically prevent problem categories, and leverage knowledge systems effectively. - -**Confidence Check**: Can the agent explain the decision rationale? Is the decision based on context understanding or automated response? Does the decision prevent future problem instances? diff --git a/.pongogo/instructions/agentic_workflows/multi_pass_iterative_analysis.instructions.md b/.pongogo/instructions/agentic_workflows/multi_pass_iterative_analysis.instructions.md deleted file mode 100644 index a872eb34..00000000 --- a/.pongogo/instructions/agentic_workflows/multi_pass_iterative_analysis.instructions.md +++ /dev/null @@ -1,404 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Multi-Pass Iterative Analysis" -description: "Multi-pass iterative analysis methodology for complex tasks requiring progressive refinement." -applies_to: - - "**/*" -domains: - - "agentic_workflows" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 1 - triggers: - keywords: - - multi-pass - - iterative_analysis - - cross-reference - - N-to-N - - gardening - - triage - - audit - - prioritization - - classification - - reconciliation - - staleness_assessment - - overlap_detection - nlp: "Structured methodology for analyzing collections with comprehensive cross-referencing" -evaluation: - success_signals: - - All items in scope enumerated (inventory pass) - - N-to-N cross-referencing performed - - Running notes file created before analysis starts - - Evidence annotation for each classification decision - - Actions executed immediately after category approval - failure_signals: - - Items missed in inventory - - Cross-reference pass skipped - - No tracking file (context loss unrecoverable) - - Classification without evidence - - Actions batched at end instead of immediate execution ---- - - -# Multi-Pass Iterative Analysis Pattern - -**Purpose**: Structured methodology for analyzing collections of items (issues, PIs, files, patterns) for classification, prioritization, or reconciliation using explicit N-to-N cross-referencing. - -**Core Principle**: When analyzing a collection, partial context leads to missed relationships. The multi-pass approach with explicit cross-referencing ensures completeness. - -**When to Apply**: -- PI system gardening -- Issue triage/pruning -- Milestone priority evaluation -- Pattern library extraction -- Documentation audit -- Any "review all X and decide Y" task - ---- - -## Quick Reference - -### The Seven Passes - -| Pass | Name | Purpose | Output | -|------|------|---------|--------| -| 1 | **Inventory** | Enumerate all items in scope | Item list with metadata | -| 2 | **Clustering** | Group by source/theme/relationship | Cluster map | -| 3 | **Individual Assessment** | Evaluate each item against criteria | Per-item analysis | -| 4 | **Cross-Reference** | Compare each item vs ALL others | Relationship matrix | -| 5 | **Classification** | Assign category/priority/status | Classification decisions | -| 6 | **Reconciliation** | Resolve conflicts/overlaps | Action plan | -| 7 | **Action** | Execute decisions with tracking | Completed actions | - -### Rigor Levels - -| Level | Use Case | Passes Used | Cross-Reference Scope | -|-------|----------|-------------|----------------------| -| **Quick Scan** | Spot-check, minor changes | 1, 3, 5 | Obvious relationships only | -| **Standard** | Regular gardening, re-triage | 1-5, 7 | Within-cluster comparison | -| **Comprehensive** | First analysis, milestone boundaries | All 7 | N-to-N (ALL items) | - -**Default Selection**: -- First analysis of a scope: **Comprehensive** -- Re-analysis after prior pass: **Standard** -- Quick hygiene check: **Quick Scan** - ---- - -## Core Principles - -### N-to-N Cross-Referencing - -**The differentiator**: Every item compared against every other item at least once. - -**Why this matters**: -- Partial comparison misses non-obvious relationships -- Items may overlap with "unrelated" clusters -- Hidden dependencies only visible through comprehensive review - -**Implementation**: -``` -For item A in collection: - For item B in collection (B ≠ A): - Assess: Does A relate to B? (overlap, dependency, conflict) - Record: Relationship type and evidence -``` - -**Scaling**: For large collections (50+ items), batch by cluster then cross-reference across clusters. - -### Cluster-First Analysis - -**Before individual analysis, identify clusters**: - -1. Scan all item titles/summaries -2. Group by source (same Epic, same domain, same type) -3. Label clusters with descriptive names -4. Process clusters together to identify within-cluster relationships - -**Example Clusters**: -- Cluster A: "Learning Loop Documentation" (#1, #2, #3, #4) -- Cluster B: "Epic Documentation Gaps" (#5, #6, #7) -- Cluster C: "Research Spikes" (#8, #9, #10) - -**Why cluster first**: -- Identifies obvious relationships early -- Reduces cognitive load during individual assessment -- Enables batch decisions for homogeneous clusters - -### Running Notes (Context Preservation) - -**MANDATORY**: Create tracking file before starting. - -**Required Contents**: -1. **Status tracker**: Phase/pass progress, counts, completion status -2. **Item-by-item table**: ID, cluster, analysis completed, classification -3. **Evidence annotations**: Rationale for each decision -4. **Cross-reference notes**: Relationships discovered - -**Purpose**: Enable recovery after context loss (auto-compact, session break). - -**Template**: -```markdown -# Analysis Tracking: [SCOPE] - [DATE] - -## Progress -- Pass 1 (Inventory): ✅ Complete (N items) -- Pass 2 (Clustering): ✅ Complete (X clusters) -- Pass 3 (Individual): 🔄 In Progress (Y/N complete) -- Pass 4 (Cross-Reference): ⏳ Pending -... - -## Item Analysis Table -| ID | Cluster | Pass 3 | Pass 4 | Classification | Evidence | -|----|---------|--------|--------|----------------|----------| -| #1 | A | ✅ | ✅ | VALID | No overlaps found | -| #2 | A | ✅ | 🔄 | - | Checking vs #5 | -... - -## Relationships Discovered -- #1 and #5: Partial overlap (~30%), reconciliation needed -- #3 blocks #7: Dependency discovered -... -``` - ---- - -## Pass Descriptions - -### Pass 1: Inventory - -**Goal**: Complete enumeration of all items in scope with metadata. - -**Actions**: -1. Query/list all items in scope -2. Capture: ID, title, created date, last modified, current status -3. Verify count matches expectations -4. Record in tracking file - -**Output**: Item list with metadata - -**Verification**: "I expect N items. I have retrieved N items." - -### Pass 2: Clustering - -**Goal**: Group items by source/theme before individual analysis. - -**Actions**: -1. Scan all titles for patterns -2. Identify grouping criteria (source Epic, domain, type, date range) -3. Assign each item to exactly one cluster -4. Label clusters descriptively -5. Record cluster map in tracking file - -**Output**: Cluster map (Cluster → Items) - -**Cluster Naming**: Use descriptive names, not just letters. -- Good: "Learning Loop Documentation Layer Gap" -- Bad: "Cluster A" - -### Pass 3: Individual Assessment - -**Goal**: Evaluate each item against defined criteria. - -**Actions**: -1. Read full item content (body, comments, history) -2. Apply assessment criteria (depends on analysis type) -3. Note initial classification hypothesis -4. Flag items needing cross-reference attention -5. Record analysis in tracking file - -**Output**: Per-item analysis notes - -**Assessment Criteria Examples**: -- Triage: Staleness indicators, blocker status, scope clarity -- Prioritization: Dependency unlocking, quality improvement, time to value -- PI Gardening: Corrective vs exploratory, confidence level, staleness - -### Pass 4: Cross-Reference - -**Goal**: Compare each item against all others to find relationships. - -**Actions**: -1. For each item, compare against all others in scope -2. Identify: Overlaps, dependencies, conflicts, supersession -3. Record relationship type and evidence -4. Flag items needing reconciliation -5. Update tracking file with relationships - -**Output**: Relationship discoveries - -**Relationship Types**: -- **Overlap**: Partial scope intersection (requires reconciliation) -- **Dependency**: A blocks B or A enables B -- **Supersession**: Newer item replaces older item's scope -- **Conflict**: Mutually exclusive approaches -- **None**: Independent items - -**Comprehensive vs Standard**: -- Comprehensive: Compare ALL items vs ALL items -- Standard: Compare within clusters + spot-check across clusters - -### Pass 5: Classification - -**Goal**: Assign final category/priority/status to each item. - -**Actions**: -1. Review Pass 3 (individual) and Pass 4 (cross-reference) findings -2. Apply classification criteria -3. Assign category with evidence -4. Update tracking file - -**Output**: Classification decisions with evidence - -**Evidence Annotation Format**: -``` -VALID - [STATUS] (N-pass verified YYYY-MM-DD: [evidence summary]) -``` - -### Pass 6: Reconciliation - -**Goal**: Create action plan for conflicts, overlaps, dependencies. - -**Actions**: -1. For each flagged relationship, determine resolution -2. Apply resolution principles (recency bias, scope clarity, etc.) -3. Create reconciliation plan -4. Document in tracking file - -**Output**: Reconciliation action plan - -**Resolution Principles**: -- **Recency Bias**: Favor newer items when scope overlaps -- **Consolidation**: Merge unique details into primary item -- **Dependency Ordering**: Ensure blockers resolved before dependents - -### Pass 7: Action - -**Goal**: Execute decisions with tracking and verification. - -**Actions**: -1. Present findings for approval (interactive) -2. Execute approved actions immediately (not batched) -3. Record actions taken -4. Verify completion - -**Output**: Completed actions with evidence - -**Interactive Workflow**: -1. Present summary (counts by category) -2. Walk through each category -3. Get approval via AskUserQuestion -4. Execute immediately -5. Confirm completion -6. Move to next category - ---- - -## Application Examples - -### PI System Gardening - -**Inventory**: List all PI files with metadata (created, modified, confidence) -**Clustering**: Group by domain, confidence level, or source task -**Assessment Criteria**: Corrective vs exploratory, staleness, duplicate detection -**Classification**: KEEP, ARCHIVE, MERGE, MIGRATE_TO_RH -**Action**: Update PI index, archive stale items, merge duplicates - -### Issue Triage - -**Inventory**: Query project board for target column -**Clustering**: Group by Epic, domain, type -**Assessment Criteria**: Staleness indicators, blocker status, scope clarity -**Classification**: VALID, STALE, SUPERSEDED, DUPLICATE, PREMATURE -**Action**: Close, move, or keep with updated status - -### Milestone Priority Evaluation - -**Inventory**: List all issues in milestone -**Clustering**: Group by dependency chain, domain -**Assessment Criteria**: Dependency unlocking, quality improvement, time to value -**Classification**: Priority order with rationale -**Action**: Update milestone body, create blocking relationships - ---- - -## Anti-Patterns - -### Skip Cross-Reference Pass - -**Problem**: "I'll just assess each item individually" -**Risk**: Missed relationships, duplicate work, incorrect classifications -**Fix**: Always include Pass 4, adjust rigor level for scope - -### No Running Notes - -**Problem**: "I'll remember where I was" -**Risk**: Context loss makes recovery impossible -**Fix**: Create tracking file BEFORE starting, update in real-time - -### Batch Actions at End - -**Problem**: "I'll execute all actions after analysis complete" -**Risk**: Decision fatigue, context drift, missed approvals -**Fix**: Execute actions immediately after each category approval - -### Skip Clustering - -**Problem**: "I'll just process items in order" -**Risk**: Miss within-cluster relationships, inefficient processing -**Fix**: Always cluster first, even if clusters seem obvious - ---- - -## Integration with Other Patterns - -### Retrospective Depth Selection - -Multi-pass analysis can trigger retrospectives: -- Analysis reveals systemic issues → L3 retrospective -- Pattern emerges across items → L2 pattern extraction -- Routine gardening → L1 work log entry - -### Issue Commencement/Closure - -Multi-pass analysis tasks follow standard commencement/closure: -- Commence: Status transitions, project status update -- Closure: Checklist, learning loop, cross-issue updates - -### PI System - -Multi-pass analysis may create PI entries: -- Recurring pattern discovered → Track in PI -- Process gap identified → Create PI - ---- - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| Missing relationships | Skipped cross-reference pass | Run Pass 4 comprehensively | -| Context loss during analysis | No tracking file | Create tracking file, resume from last recorded position | -| Inconsistent classifications | No evidence annotation | Re-run with explicit evidence recording | -| Scope creep during analysis | No inventory verification | Verify item count matches expectations | -| Decision paralysis | Too many items at once | Batch by cluster, process one cluster at a time | - ---- - -## Related Instructions - -- **Milestone Governance**: `milestone_governance.instructions.md` -- **PI System**: `potential_improvements.md` - ---- - -**Success Criteria**: Analysis produces complete, consistent classifications with evidence trail that survives context loss and enables audit. - -**Confidence Check**: -1. Did I enumerate ALL items in scope? -2. Did I compare each item against ALL others (appropriate to rigor level)? -3. Can I point to evidence for each classification? -4. Can someone resume from my tracking file after context loss? diff --git a/.pongogo/instructions/architecture/repository_organization.instructions.md b/.pongogo/instructions/architecture/repository_organization.instructions.md deleted file mode 100644 index 1c8d9454..00000000 --- a/.pongogo/instructions/architecture/repository_organization.instructions.md +++ /dev/null @@ -1,527 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Repository Organization" -description: "Repository structure and organization standards for consistent codebase layout." -applies_to: - - "**/*" -domains: - - "architecture" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 1 - triggers: - keywords: - - directory_structure - - repository_organization - - nested_+_prefixed - - nested_prefixed - - root_cleanliness - - autocomplete - - at_selector - - self-documenting_names - - directory_naming - - folder_structure - - gitignore_patterns - - consistent_depth - - root_pollution - - parent_directory - - subdirectory_naming - - multi-stakeholder_optimization - nlp: "Organizing repository directories for both human navigation and tool-based autocomplete using nested + prefixed patterns" -evaluation: - success_signals: - - Root directory under 15 items (excluding hidden) - - Related directories grouped under parent - - Nested + prefixed pattern applied - - Self-documenting names (full words, not abbreviations) - - "@ autocomplete works for prefixed directories" - failure_signals: - - Root pollution (many related items at root) - - Pure nesting without prefixes (ambiguous autocomplete) - - Cryptic abbreviations in directory names - - Inconsistent depth across parallel categories - - Code breaks due to hardcoded paths after refactoring ---- - - -# Repository Organization Patterns - -**Purpose**: Establish repository organization patterns optimizing for both human navigation and tool-based operations through nested + prefixed directory structures. - -**Philosophy**: Best directory structures serve ALL stakeholders (humans, tools, agents) through synthesis, not compromise. - ---- - -## When to Apply - -- Creating new directory structures for features -- Noticing >3 related directories at same level -- Root directory contains >10 items (excluding config files) -- Directory purpose requires documentation to understand -- Tool-based file operations common (@ selectors, autocomplete) -- Planning directory structure for multi-mode systems (test/prod/dev) - ---- - -## Quick Reference - -**Nested + Prefixed Pattern**: - -``` -✅ Best of both worlds: -logs/ - logs-production/ ← @logs- autocompletes to all log dirs - logs-testing/ - logs-learning/ -.observability_db/ - observability_db-production/ ← @observability_db- autocompletes - observability_db-testing/ - observability_db-learning/ -``` - -**Anti-Patterns to Avoid**: - -``` -❌ Pure nesting (poor autocomplete): -logs/ - production/ ← @production matches many things - testing/ ← @testing ambiguous - -❌ Pure prefixing (root pollution): -logs-production/ -logs-testing/ -observability_db-production/ -observability_db-testing/ -``` - -**Benefits**: -- Root cleanliness: Parent directories group related items -- Tool optimization: Prefix-based @ autocomplete works -- Self-documenting: Full names over abbreviations -- Human navigable: Hierarchy provides organization - ---- - -## Core Principles - -- **Multi-Stakeholder Optimization**: Serve tools (@autocomplete) AND humans (navigation), not either/or -- **Self-Documenting Names**: Directory purpose should be immediately clear without context -- **Root Cleanliness**: Keep root scannable (<15 items), group related items under parent directories -- **Consistent Depth**: Maintain parallel structure across similar categories (don't mix flat and deep) -- **Scalability First**: Structure should accommodate future growth without root pollution - -## Step-by-Step Guidance - -### 1. Identify Related Directory Groups - -**Action**: Find directories that share purpose or category - -**Questions to Ask**: -- Do 3+ directories serve similar purpose? (logs, configs, tests) -- Do directory names share common prefixes? (test-*, prod-*, dev-*) -- Would grouping improve scanability? - -**Example Analysis**: -``` -❌ Before (6 root-level directories): -logs/ -test-logs/ -learning-logs/ -.observability/ -.test-observability/ -.learning-observability/ - -✅ After (2 parent directories): -logs/ ← Group all log-related -.observability_db/ ← Group all observability-related -``` - -**Success Indicator**: >3 related items identified for consolidation - ---- - -### 2. Design Parent Directory Structure - -**Action**: Create clear, descriptive parent directory names - -**Naming Guidelines**: -- Use full words, not abbreviations (`logs/` not `lg/`) -- Choose category name that encompasses all children -- Consider if directory will be hidden (`.observability_db/` for generated content) -- Avoid generic names (`data/`, `misc/`, `stuff/`) - -**Example Decisions**: -- `logs/` for all event logs (production, testing, learning) -- `.observability_db/` for generated databases (hidden, rebuildable) -- `configs/` for all configuration files (dev, staging, prod) -- `docs/` for all documentation (guides, reference, API) - -**Why Hidden Directories**: -- Generated content (`.observability_db/`) -- IDE-specific files (`.vscode/`) -- Build artifacts (`.cache/`) -- Use `.` prefix to hide from casual listing - ---- - -### 3. Apply Nested + Prefixed Pattern - -**Action**: Add parent directory prefix to subdirectory names - -**Pattern Formula**: -``` -parent_directory/ - parent_directory-mode_1/ - parent_directory-mode_2/ - parent_directory-mode_3/ -``` - -**Why Add Prefix**: -- Tool autocomplete works: `@logs-` matches all log directories -- Unambiguous matching: `@logs-production` doesn't match `production/` in other contexts -- Self-documenting: `logs-production` is clearer than just `production` - -**When NOT to Prefix**: -- Single subdirectory (no ambiguity) -- Subdirectory names already unique (`docs/api-reference/`, `docs/user-guides/`) -- Deep nesting where prefix becomes redundant - -**Example Application**: -``` -configs/ - configs-development/ ← @configs- autocompletes - configs-staging/ - configs-production/ - -tests/ - tests-unit/ ← @tests- autocompletes - tests-integration/ - tests-e2e/ -``` - ---- - -### 4. Maintain Consistent Structure Depth - -**Action**: Keep parallel categories at same depth level - -**Good Example** (consistent depth): -``` -logs/ - logs-production/ - logs-testing/ - logs-learning/ - -.observability_db/ - observability_db-production/ - observability_db-testing/ - observability_db-learning/ -``` - -**Bad Example** (inconsistent depth): -``` -logs/ - logs-production/ - test/ - integration/ ← Inconsistent depth - unit/ - learning-dataset-logs/ ← Mixed naming -``` - -**Why Consistency Matters**: -- Predictable navigation patterns -- Easier to understand structure -- Simpler path construction in code -- Reduces cognitive load - ---- - -### 5. Update Code and Documentation - -**Action**: Update all references to use new structure - -**Code Updates**: -```python -# Before (hardcoded paths) -log_path = "/logs/" -test_log_path = "/test-logs/" - -# After (centralized path construction) -def get_log_path(mode: str) -> Path: - base = Path("logs") - if mode == 'testing': - return base / "logs-testing" - elif mode == 'learning': - return base / "logs-learning" - else: - return base / "logs-production" -``` - -**Documentation Updates**: -- `.gitignore`: Update patterns for new structure -- `README.md`: Update directory structure documentation (if exists) -- Architecture docs: Update diagrams showing directory layout -- Setup guides: Update paths in installation instructions - -**Example .gitignore**: -```gitignore -# Observability data (nested + prefixed structure) -# - logs/logs-{production,testing,learning}/ - JSONL event logs -# - .observability_db/observability_db-{production,testing,learning}/ - SQLite databases -.observability_db/ -logs/ -``` - ---- - -## Examples - -### Example 1: Multi-Mode Logging Structure - -``` -# Task: Organize logs for production, testing, and learning modes -# Requirement: Clean root, @ autocomplete support - -✅ Nested + Prefixed Solution: -logs/ - logs-production/ - routing-events-2025-11-10.jsonl - logs-testing/ - routing-events-2025-11-10.jsonl - logs-learning/ - routing-events-2025-11-10.jsonl - -Benefits: -- Root: 1 directory (not 3) -- @logs- autocompletes to all log directories -- Immediately clear: "logs-production" = production logs -- Scalable: Add logs-benchmarking/ without root pollution -``` - -**Context**: Gen 1 Observability with log isolation - -**Result**: 67% reduction in root-level clutter (6 dirs → 2 dirs) - ---- - -### Example 2: Configuration Management - -``` -# Task: Organize configurations for dev, staging, production environments -# Requirement: Clear separation, tool-friendly navigation - -✅ Nested + Prefixed Solution: -configs/ - configs-development/ - database.yml - api_keys.yml - configs-staging/ - database.yml - api_keys.yml - configs-production/ - database.yml - api_keys.yml - -Code Integration: -```python -from pathlib import Path - -def get_config_path(environment: str) -> Path: - """Get configuration directory for environment.""" - configs_base = Path("configs") - return configs_base / f"configs-{environment}" - -# Usage -config_dir = get_config_path("production") -db_config = config_dir / "database.yml" -``` - -**Context**: Multi-environment application deployment - -**Trade-offs**: Slightly longer paths, but significantly better autocomplete and clarity - ---- - -### Example 3: Refactoring Flat Structure - -``` -# Before (root pollution - 8 directories): -src/ -tests/ -test-data/ -test-results/ -docs/ -doc-examples/ -doc-api-reference/ -scripts/ - -# After (nested + prefixed - 4 directories): -src/ -tests/ - tests-unit/ - tests-integration/ - tests-e2e/ - tests-data/ ← Test data grouped with tests - tests-results/ ← Test results grouped with tests -docs/ - docs-guides/ - docs-examples/ - docs-api-reference/ -scripts/ - -Result: -- Root directories: 8 → 4 (50% reduction) -- Related items grouped logically -- @tests- and @docs- autocomplete working -``` - -**Refactoring Steps**: -1. Create parent directories (`tests/`, `docs/`) -2. Create prefixed subdirectories (`tests-unit/`, `docs-guides/`) -3. Move content from flat structure -4. Update code references -5. Update .gitignore patterns -6. Test that @ autocomplete works - ---- - -## Validation Checklist - -- [ ] Root directory has <15 items (excluding hidden files) -- [ ] Related directories grouped under parent directories -- [ ] Subdirectories use parent name as prefix -- [ ] Directory names are full words (not abbreviations) -- [ ] Consistent depth maintained across parallel categories -- [ ] @ autocomplete tested and working -- [ ] Code updated for new paths -- [ ] .gitignore patterns updated -- [ ] Documentation reflects new structure -- [ ] Can navigate structure easily (human test) - ---- - -## Common Pitfalls - -### Pitfall 1: Pure Nesting Without Prefixes - -- ❌ **Problem**: Generic subdirectory names harm @ autocomplete -- **Example**: `logs/production/` makes `@production` ambiguous -- **Why it happens**: Optimizing only for human directory navigation -- ✅ **Solution**: Add parent name as prefix (`logs/logs-production/`) -- **Trade-off**: Slightly redundant path, but massive autocomplete improvement - -### Pitfall 2: Pure Prefixing Without Nesting - -- ❌ **Problem**: Root directory gets polluted with many related items -- **Example**: `logs-production/`, `logs-testing/`, `logs-learning/` all at root -- **Why it happens**: Optimizing only for tool autocomplete -- ✅ **Solution**: Nest under parent directory (`logs/logs-production/`) -- **Trade-off**: Extra directory level, but root stays clean - -### Pitfall 3: Cryptic Abbreviations - -- ❌ **Problem**: Directory purpose unclear without domain knowledge -- **Example**: `logs/prod/`, `logs/dev/`, `logs/tst/` -- **Why it happens**: Optimizing for brevity over clarity -- ✅ **Solution**: Use full words (`logs-production`, `logs-development`, `logs-testing`) -- **Benefit**: Self-documenting, no abbreviation lookup needed - -### Pitfall 4: Inconsistent Depth - -- ❌ **Problem**: Some categories flat, others deeply nested -- **Example**: - ``` - logs/ - production/ - tests/ - unit/ - integration/ - e2e/ ← Inconsistent depth - ``` -- **Why it happens**: Evolving structure without refactoring -- ✅ **Solution**: Maintain parallel depth for similar categories -- **Example**: - ``` - logs/ - logs-production/ - tests/ - tests-unit/ - tests-integration/ - tests-e2e/ - ``` - ---- - -## Edge Cases - -### Edge Case 1: Single Subdirectory - -**When**: Only one subdirectory under parent (e.g., `logs/` with only `production/`) - -**Approach**: Don't add prefix yet - wait for second subdirectory -- `logs/production/` is fine for single mode -- Add prefix when adding second mode (`logs-production/`, `logs-testing/`) -- Prevents premature optimization - -**Example**: -``` -# Start simple -logs/ - production/ - -# Add prefix when scaling -logs/ - logs-production/ - logs-testing/ ← Now prefix makes sense -``` - -### Edge Case 2: Already Unique Subdirectory Names - -**When**: Subdirectories have unique, descriptive names already - -**Approach**: Prefix optional if no ambiguity -- `docs/api-reference/` is already unique -- `docs/user-guides/` is already unique -- No need for `docs-api-reference/` prefix - -**Decision Framework**: -- Will `@api-reference` match multiple things? No → skip prefix -- Is subdirectory name generic (`production`, `testing`)? Yes → add prefix - -### Edge Case 3: Very Long Directory Names - -**When**: Parent + prefix creates unwieldy paths - -**Approach**: Shorten parent name or accept trade-off -- `observability_db-production` vs `obs_db-production` -- Prefer clarity over brevity -- Long paths better than ambiguous autocomplete - ---- - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| @ autocomplete returns too many matches | Generic subdirectory names | Add parent prefix to subdirectories | -| Root directory cluttered | Related items not grouped | Create parent directories, nest related items | -| Can't find directories | Non-descriptive names | Use full words, add context to names | -| Inconsistent navigation | Mixed flat and deep structure | Standardize depth across parallel categories | -| Code breaks after refactoring | Hardcoded paths | Centralize path construction logic | -| Unclear directory purpose | Abbreviations or generic names | Use self-documenting full names | - ---- - -## Related Instructions - -- **See also**: [Naming and Organization](../../standards/naming_and_organization.md) - Overall naming conventions -- **Related**: [Project Organization Standards](../../standards/project_organization_standards.md) - Project structure guidelines - ---- - -**Success Criteria**: Root directory scannable (<15 items), @ autocomplete returns correct directories, structure is self-documenting - -**Confidence Check**: Can a new contributor understand the directory structure in <2 minutes without documentation? If yes, organization is successful. diff --git a/.pongogo/instructions/development/token_usage_context_management.instructions.md b/.pongogo/instructions/development/token_usage_context_management.instructions.md deleted file mode 100644 index 03722971..00000000 --- a/.pongogo/instructions/development/token_usage_context_management.instructions.md +++ /dev/null @@ -1,509 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Token Usage and Context Management" -description: "Guidance for managing token usage, context windows, and conversation efficiency." -applies_to: - - "**/*" -domains: - - "development" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 1 - triggers: - keywords: - - token_usage - - context_window - - context_management - - token_cost - - /compact - - session_restart - - context_preservation - - context_exhaustion - - 200K_token - - context_window_limit - - proactive_compacting - - session_state_transfer - - work_log_offload - - strategic_preservation - - completeness_over_cost - nlp: "Managing token usage and context window to preserve operational capacity rather than minimizing cost" -evaluation: - success_signals: - - Completeness never sacrificed for token cost - - Context window monitored at thresholds (150K+) - - Strategic compacting preserves high-value recent context - - Work log used for context offload - - Quality-driven verbosity decisions - failure_signals: - - Content truncated to save token costs - - Context window exhaustion mid-session - - Premature compacting (before 100K tokens) - - "Arbitrary context removal (oldest N%)" - - Ignoring context window entirely ---- - - -# Token Usage and Context Window Management - -**Purpose**: Establish principles for token usage optimization focusing on context window preservation (operational concern) rather than cost minimization (non-concern). - -**Philosophy**: Token costs are negligible expense. Context window exhaustion is operational failure. Optimize for preserving context window capacity, not reducing token spend. - -**Core Problem Solved**: "When should I worry about token usage, and when should I ignore it?" - ---- - -## Quick Reference - -### The Two Token Concerns - -**Token Cost** (Expense): -- **Concern Level**: ZERO - Not something we worry about -- **Why**: Token costs are negligible in typical operating budgets -- **Action**: Never optimize for cost reduction, never truncate for cost savings -- **Example**: Don't summarize comprehensive RCA to save tokens on API calls - -**Context Window** (Operational Capacity): -- **Concern Level**: HIGH - Critical operational concern -- **Why**: Losing context mid-session = operational failure, loss of state, broken workflows -- **Action**: Monitor context window usage, manage proactively to preserve continuity -- **Example**: Compact conversation history when approaching window limit to preserve recent critical context - -### Decision Rule - -``` -Question: "Should I reduce token usage here?" - -Check WHY: -├─ To save money? → NO, ignore cost -├─ To preserve context window? → YES, manage proactively -└─ To improve quality? → Evaluate trade-offs (completeness vs brevity) -``` - ---- - -## When to Apply - -Apply this instruction when: - -- Creating comprehensive documentation (RCAs, retrospectives, instruction files) -- Deciding between verbose vs concise content -- Approaching context window limits during long sessions -- Evaluating whether to summarize or preserve full content -- Making trade-offs between completeness and token efficiency - ---- - -## Core Principles - -### Principle 1: Completeness Over Cost Efficiency - -**Principle**: Never sacrifice completeness, quality, or depth to reduce token costs. - -**Why**: Token costs are trivial (<$0.01 per 1000 tokens). Incomplete documentation creates knowledge gaps costing hours of rework. Rework time >> token cost by 1000x+. - -**Application**: -- Create comprehensive RCAs (10,000+ tokens if needed) -- Write detailed instruction files with full examples -- Include all evidence, not summaries, in retrospectives -- Preserve full context in learning artifacts -- Never truncate templates to save tokens - -**Example**: -- ❌ **Cost-optimized**: "RCA should be brief to save tokens" -- ✅ **Quality-optimized**: "RCA should be comprehensive (10K+ tokens) to capture all learnings" - -**Cost Impact**: Comprehensive RCA = ~10,000 tokens = ~$0.03 at $3/1M tokens -**Rework Cost**: Missing root cause = 2 hours rework = $200+ equivalent time - -**Trade-off**: $0.03 token cost vs $200 rework cost → Optimize for completeness - ---- - -### Principle 2: Context Window as Operational Constraint - -**Principle**: Context window exhaustion is operational failure. Monitor and manage proactively. - -**Why**: Running out of context window mid-session: -- Loses conversation state -- Breaks workflow continuity -- Requires re-establishing context (time expensive) -- May lose critical recent decisions/work - -**Application**: -- Monitor token usage during long sessions -- Use `/compact` command proactively when approaching limits -- Preserve recent critical context (last 20-30 exchanges) -- Archive older context strategically (work logs, decision summaries) -- Restart sessions when context window critically full - -**Thresholds** (for 200K token window): -- **Green** (0-100K tokens): Normal operation, no concern -- **Yellow** (100K-150K tokens): Monitor, consider strategic compacting -- **Orange** (150K-180K tokens): Proactive compacting, prioritize recent context -- **Red** (180K-200K tokens): Critical - compact immediately or restart session - -**Example**: -- Session at 175K tokens, creating comprehensive RCA -- **Action**: Complete RCA fully (don't truncate), then `/compact` to preserve recent work -- **Rationale**: Incomplete RCA wastes RCA work; compacting preserves both - ---- - -### Principle 3: Quality-Driven Verbosity Decisions - -**Principle**: When choosing verbosity level, optimize for quality and clarity, not token count. - -**Why**: Clear, comprehensive documentation prevents misunderstanding, reduces rework, enables correct agent decisions. - -**Application**: -- Instruction files: Include full examples, not just brief descriptions -- RCAs: Document complete failure chains, not just summaries -- Templates: Provide comprehensive guidance, not minimal skeletons -- Retrospectives: Capture all evidence, not cherry-picked highlights - -**Trade-off Framework**: -1. **First priority**: Quality and completeness -2. **Second priority**: Clarity and usability -3. **Third priority**: Brevity (only when quality/clarity unaffected) -4. **Never priority**: Token cost reduction - -**Example Decisions**: -- ❌ "Shorten RCA template to 2000 tokens to save costs" -- ✅ "RCA template is 15,000 tokens because comprehensive guidance prevents incomplete RCAs" -- ❌ "Summarize retrospective to 1000 tokens" -- ✅ "Retrospective is 8000 tokens because all evidence must be preserved" - ---- - -### Principle 4: Strategic Context Preservation - -**Principle**: When context window management required, preserve strategically, not arbitrarily. - -**Why**: Not all context has equal value. Recent decisions, current work, and active tasks more valuable than early session exploratory discussions. - -**Application**: - -**Preserve (High Value)**: -- Recent decisions (last 10-20 exchanges) -- Active work in progress (current task context) -- Unresolved questions or blockers -- Critical reference material for current work - -**Compact (Lower Value)**: -- Completed tasks (summarize outcomes) -- Exploratory discussions (preserve conclusions only) -- Resolved questions (preserve answers, not full discussion) -- Historical context (summarize, don't remove) - -**Never Remove**: -- Current session's key decisions -- Active task requirements -- Unfinished work state -- Critical instructions or constraints - -**Example**: -- Session at 180K tokens, working on RCA -- **Compact**: Early session exploration of related issues (preserve findings, compact discussion) -- **Preserve**: RCA creation process, recent meta-system discussion, current task state -- **Result**: Retain critical context, clear space for RCA completion - ---- - -## Context Window Management Tactics - -### Tactic 1: Proactive Compacting - -**When**: At 150K tokens (before critical threshold) - -**How**: Use `/compact` command to summarize older context while preserving recent critical exchanges - -**Preserve**: -- Last 20-30 exchanges -- Current work in progress -- Active decisions and rationale -- Unresolved questions - -**Compact**: -- Completed tasks → outcome summaries -- Exploratory discussions → key findings only -- Historical context → brief summaries - ---- - -### Tactic 2: Session Restart with State Transfer - -**When**: At 180K+ tokens, or when compacting insufficient - -**How**: -1. Summarize current session state (decisions, work in progress, next steps) -2. Save summary to work log or temporary file -3. Start new session -4. Begin with state summary to re-establish context - -**State Summary Contents**: -- Current task and status -- Key decisions made this session -- Work in progress (what's partially done) -- Next steps (what to do next) -- Critical context (constraints, requirements) - ---- - -### Tactic 3: Work Log as Context Offload - -**When**: Throughout session, especially for completed tasks - -**How**: -1. Complete task -2. Create work log entry capturing outcome -3. Reference work log in future context instead of preserving full discussion -4. Allows compacting task discussion while preserving outcome - -**Benefits**: -- Persistent context beyond session -- Enables aggressive compacting -- Provides archaeology trail -- Reduces context window pressure - ---- - -## Anti-Patterns (What NOT to Do) - -### Anti-Pattern 1: Cost-Driven Truncation - -**Error**: Reducing content quality or completeness to save token costs. - -**Example**: -- ❌ "Make RCA template brief (2000 tokens) to reduce API costs" -- ❌ "Summarize retrospective evidence to save tokens" -- ❌ "Remove examples from instruction files for efficiency" - -**Why Wrong**: Token costs negligible, quality/completeness costs enormous (hours of rework). - -**Correct Approach**: Optimize for quality, ignore token cost entirely. - ---- - -### Anti-Pattern 2: Premature Compacting - -**Error**: Compacting context before reaching yellow threshold (100K tokens). - -**Example**: -- ❌ Compacting at 50K tokens "to be safe" -- ❌ Removing context proactively when plenty of window remains - -**Why Wrong**: Premature compacting loses valuable context unnecessarily, may need it later in session. - -**Correct Approach**: Monitor, compact only when approaching thresholds (150K+ for 200K window). - ---- - -### Anti-Pattern 3: Arbitrary Context Removal - -**Error**: Removing context arbitrarily without strategic value assessment. - -**Example**: -- ❌ Removing oldest 50% of conversation mechanically -- ❌ Deleting all exchanges before certain point - -**Why Wrong**: May remove critical context (decisions, constraints, requirements) that's needed for current work. - -**Correct Approach**: Strategic preservation (keep high-value recent context, compact low-value older context). - ---- - -### Anti-Pattern 4: Ignoring Context Window Entirely - -**Error**: Not monitoring token usage, running into window limit unexpectedly. - -**Example**: -- ❌ Creating 50K token RCA at 175K token usage without checking -- ❌ No awareness of context window status - -**Why Wrong**: Hitting window limit mid-work = operational failure, lost state. - -**Correct Approach**: Monitor token usage, especially during long sessions or large artifact creation. - ---- - -## Monitoring and Thresholds - -### Token Window Monitoring - -**Claude Code provides token usage in responses**: Watch for token counts in responses -- **Format**: `Token usage: X/200000; Y remaining` -- **Frequency**: Every response includes usage -- **Action Triggers**: See thresholds in Principle 2 - -### Session Length Indicators - -**Long sessions increase context usage**: -- **Short sessions** (< 20 exchanges): Rarely concern -- **Medium sessions** (20-50 exchanges): Monitor occasionally -- **Long sessions** (50+ exchanges): Monitor continuously -- **Marathon sessions** (100+ exchanges): Proactive management critical - -### Large Artifact Creation - -**Creating large artifacts consumes context**: -- **Small** (< 2K tokens): No concern -- **Medium** (2K-5K tokens): Check remaining capacity -- **Large** (5K-10K tokens): Verify sufficient space -- **Very Large** (10K+ tokens): Consider compacting before creation - -**Example**: -- Planning to create 12K token RCA -- Current usage: 175K tokens -- Remaining: 25K tokens -- **Action**: Compact first (create space), then create RCA - ---- - -## Practical Guidelines - -### Guideline 1: Comprehensive Documentation is Always Worth Tokens - -**Situation**: Creating RCA, retrospective, instruction file, template - -**Decision**: Create as comprehensively as needed, ignore token cost - -**Rationale**: Incomplete documentation creates knowledge gaps costing hours of rework. Token cost is irrelevant compared to rework cost. - -**Token Budget**: Unlimited for quality documentation - ---- - -### Guideline 2: Monitor, Don't Micro-Optimize - -**Situation**: General development work - -**Decision**: Monitor token usage, don't optimize prematurely - -**Rationale**: Context window is large (200K tokens). Most sessions won't approach limits. Monitor, manage when needed, don't preemptively truncate. - -**Action**: Check token usage periodically, act at thresholds, ignore otherwise - ---- - -### Guideline 3: Context Preservation During Compacting - -**Situation**: Approaching context window limits (150K+ tokens) - -**Decision**: Compact strategically, preserve high-value recent context - -**Rationale**: Losing critical recent context breaks workflow. Compact completed/low-value context, keep active work state. - -**Process**: -1. Identify high-value context (recent 20-30 exchanges, current work, active decisions) -2. Identify low-value context (completed tasks, resolved questions, exploratory discussions) -3. Use `/compact` to summarize low-value, preserve high-value -4. Verify critical context retained - ---- - -### Guideline 4: Session Restart as Last Resort - -**Situation**: Context window critically full (180K+ tokens), compacting insufficient - -**Decision**: Restart session with state transfer - -**Rationale**: Better to restart with clean context than lose state mid-work to window exhaustion. - -**Process**: -1. Create comprehensive session state summary -2. Save to work log or file -3. Start fresh session -4. Load state summary at beginning -5. Continue work with full context window available - ---- - -## Related Documentation - -**Principles**: -- `complete_context_principle.instructions.md` - Complete context over sampling -- `quality_first_development.instructions.md` - Quality over efficiency - -**Operations**: -- `/compact` command - Context window management tool -- Work logging - Persistent context beyond session - -**Templates**: -- All templates optimize for quality over brevity -- RCA template, retrospective template, instruction file template - ---- - -## Examples - -### Example 1: Creating Comprehensive RCA - -**Situation**: Creating first RCA, template is 15K tokens, final RCA may be 10K+ tokens - -**Cost Optimization Approach** (WRONG): -- "RCA too long, let's make template brief (2K tokens)" -- "Reduce RCA to 3K tokens to save costs" -- **Result**: Incomplete RCA, missing critical analysis, no systematic prevention - -**Quality Optimization Approach** (CORRECT): -- "RCA template is 15K tokens because comprehensive guidance prevents incomplete RCAs" -- "This RCA is 10K tokens because it captures complete failure chain, prevention frameworks, patterns" -- **Result**: Comprehensive RCA, systematic prevention, reusable meta-system -- **Token Cost**: ~25K tokens = ~$0.08 at $3/1M tokens -- **Value**: Prevents future incidents (hours of cost), establishes reusable framework - ---- - -### Example 2: Long Session Context Management - -**Situation**: 180K token usage, creating final RCA, need 20K more tokens - -**Arbitrary Truncation** (WRONG): -- Remove oldest 50% of conversation -- **Risk**: May lose critical decisions, constraints, or context - -**Strategic Preservation** (CORRECT): -1. Identify completed work earlier in session → Summarize outcomes -2. Preserve recent meta-system discussion → Keep full context -3. Use `/compact` to reduce completed work, keep active context -4. Verify RCA creation context preserved -5. Create RCA with full context available - ---- - -### Example 3: Cost vs Quality Trade-off - -**Situation**: Should instruction file include full examples or brief descriptions? - -**Cost-Driven** (WRONG): -- "Brief descriptions save tokens" -- 500 token instruction file (minimal) -- **Result**: Agents misunderstand, need clarification, create incorrect implementations - -**Quality-Driven** (CORRECT): -- "Full examples prevent misunderstanding" -- 3000 token instruction file (comprehensive) -- **Result**: Agents understand correctly, implement accurately, no rework -- **Token Cost**: 2500 additional tokens = ~$0.008 -- **Rework Avoided**: 1 hour = $100+ equivalent -- **ROI**: $0.008 cost vs $100 value = 12,500x return - ---- - -## Change Log - -### 2025-11-16 (v1.0.0) -- Initial creation -- Established core principles: completeness over cost, context window as operational constraint -- Defined monitoring thresholds and management tactics -- Documented anti-patterns and practical guidelines -- Clarified token cost (negligible) vs context window (critical operational concern) - ---- - -**Version**: 1.0.0 -**Last Updated**: 2025-11-16 diff --git a/.pongogo/instructions/devops/audit_logging_patterns.instructions.md b/.pongogo/instructions/devops/audit_logging_patterns.instructions.md deleted file mode 100644 index 4d58081d..00000000 --- a/.pongogo/instructions/devops/audit_logging_patterns.instructions.md +++ /dev/null @@ -1,528 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Audit Logging Patterns" -description: "Audit logging patterns for compliance, debugging, and operational visibility." -applies_to: - - "**/*" -domains: - - "devops" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 1 - triggers: - keywords: - - audit_logging - - audit_service - - audit_client - - decision_logging - - reasoning_capture - - causality_chain - - parent_event_id - - correlation_id - - root_event_id - - rollback_support - - meta-learning - - training_dataset - - decision_event - - change_tracking - - before/after - - alternatives_considered - - confidence_score - - structured_logging - nlp: "Audit service logging patterns for capturing decisions, reasoning, causality chains, and enabling rollback and meta-learning" -evaluation: - success_signals: - - All AI decisions logged with reasoning and confidence - - Correlation IDs propagated across service calls - - Before/after states captured for changes - - Rollback strategy defined for reversible operations - - Alternatives considered documented for decisions - failure_signals: - - Decisions logged without reasoning or confidence - - Missing correlation IDs (can't trace across services) - - No before/after snapshots for state changes - - Rollback data insufficient for undo - - Unstructured log messages (not JSON) ---- - - -# Audit Logging Patterns - -## Context - -The Audit Service is the **primary training dataset** for meta-learning. Every decision, reasoning step, outcome, and feedback must be captured immutably. - ---- - -## Quick Reference - -**Key Audit Logging Patterns (Code Examples)**: - -**1. Simple Event Log**: -```typescript -await auditClient.recordEvent({ - event_type: 'knowledge.created', - service: 'knowledge-extraction', - correlation_id: correlationId, - context: { - artifact_id: 'new-instruction', - file_path: 'knowledge/instructions/workflow/new.md' - }, - outcome: { - status: 'success', - result: { concept_id: 'new-concept' } - } -}); -``` - -**2. Decision Event with Reasoning**: -```typescript -await auditClient.recordDecision({ - event_type: 'learning.instruction_proposed', - service: 'learning-service', - correlation_id: correlationId, - - decision: { - decision_type: 'instruction_proposal', - input: { - pattern_frequency: 5, - contexts: ['CI timeout', 'test parallelization'] - }, - reasoning: 'Detected recurring CI timeout pattern across 5 work log entries. Pattern shows consistent solution: test parallelization. High confidence this is generalizable.', - confidence: 0.87, - alternatives_considered: [ - { - option: 'Do not propose (confidence too low)', - score: 0.87, - rejected_reason: 'Confidence exceeds threshold of 0.80' - } - ], - model_version: 'pattern-extractor-v1.2' - }, - - outcome: { - status: 'success', - result: { proposal_id: 'prop-789' } - } -}); -``` - -**3. Causality Chain (Parent/Child Events)**: -```typescript -// Root event -const rootEventId = await auditClient.recordEvent({ - event_type: 'routing.request', - service: 'routing-service', - correlation_id: correlationId, - outcome: { status: 'pending' } -}); - -// Child event (caused by root) -await auditClient.recordEvent({ - event_type: 'routing.candidates_selected', - service: 'routing-service', - correlation_id: correlationId, - parent_event_id: rootEventId, // Links to root - root_event_id: rootEventId, - outcome: { - status: 'success', - result: { total_candidates: 23, filtered: 8 } - } -}); -``` - -**4. Change Tracking (Before/After)**: -```typescript -await auditClient.recordEvent({ - event_type: 'artifact.updated', - context: { artifact_id: 'inst-123' }, - outcome: { - status: 'success', - changes: [{ - entity_type: 'artifact', - entity_id: 'inst-123', - operation: 'update', - before: { status: 'draft', version: '1.0.0' }, - after: { status: 'active', version: '1.1.0' }, - diff: '+ status: active\n- status: draft' - }] - }, - rollback: { - can_rollback: true, - rollback_strategy: 'revert_to_version_1.0.0' - } -}); -``` - -**5. Error Logging with Context**: -```typescript -try { - await processRequest(); -} catch (error) { - await auditClient.recordEvent({ - event_type: 'routing.error', - service: 'routing-service', - correlation_id: correlationId, - context: { - file_path: request.file_path, - error_location: 'pattern_matching_phase' - }, - outcome: { - status: 'failure', - error: { - code: error.code, - message: error.message, - stack: error.stack - } - } - }); -} -``` - -**6. Structured Logging (Good vs Bad)**: -```typescript -// ✅ Good: Structured data -await auditClient.recordEvent({ - context: { - file_path: 'src/api/auth.ts', - domains: ['backend'], - languages: ['typescript'] - }, - outcome: { status: 'success', result: { count: 5 } } -}); - -// ❌ Bad: Unstructured string -await auditClient.recordEvent({ - context: { message: 'Processing src/api/auth.ts' } -}); -``` - -**7. Always Include Alternatives**: -```typescript -// ✅ Good: Shows decision process -alternatives_considered: [ - { option: 'Approve automatically', score: 0.87, rejected_reason: 'N/A - chosen' }, - { option: 'Send for manual review', score: 0.87, rejected_reason: 'Below review threshold' }, - { option: 'Reject', score: 0.87, rejected_reason: 'Above rejection threshold' } -] - -// ❌ Bad: No alternatives -alternatives_considered: [] -``` - ---- - -## Core Principles - -1. **Log Everything**: All decisions, outcomes, and state changes -2. **Capture Reasoning**: Record why decisions were made, not just what happened -3. **Maintain Causality**: Link events in chains (parent_event_id, correlation_id) -4. **Enable Rollback**: Include enough data to undo changes -5. **Support Meta-Learning**: Structure events for aggregate analysis - -## When to Log to Audit - -**Always Log**: -- AI/automated decisions (with confidence, alternatives, reasoning) -- State changes (with before/after snapshots) -- Failures and errors (with full context) -- User feedback (explicit and implicit) -- System threshold/parameter changes - -**Examples**: -- Learning Service proposes instruction → Log with pattern analysis -- Routing Service selects instructions → Log with ranking logic -- Registry Service updates artifact → Log with diff -- Auto-approval decision → Log with confidence calculation - -## Audit Client Usage - -### Setup - -```typescript -// services/shared/audit-client.ts -import { AuditClient } from '{package}/audit-client'; - -export const auditClient = new AuditClient({ - serviceUrl: process.env.AUDIT_SERVICE_URL || 'http://audit:3008', - serviceName: process.env.SERVICE_NAME -}); -``` - -### Simple Event - -```typescript -// Record a basic event -await auditClient.recordEvent({ - event_type: 'knowledge.created', - service: 'knowledge-extraction', - correlation_id: correlationId, - context: { - artifact_id: 'new-instruction', - file_path: 'knowledge/instructions/workflow/new.md' - }, - outcome: { - status: 'success', - result: { concept_id: 'new-concept' } - } -}); -``` - -### Decision Event (with Reasoning) - -```typescript -// Record an AI/automated decision -await auditClient.recordDecision({ - event_type: 'learning.instruction_proposed', - service: 'learning-service', - correlation_id: correlationId, - parent_event_id: analysisEventId, - - decision: { - decision_type: 'instruction_proposal', - input: { - pattern_frequency: 5, - contexts: ['CI timeout', 'test parallelization'], - source_artifacts: ['work-log-1', 'work-log-2'] - }, - reasoning: 'Detected recurring CI timeout pattern across 5 work log entries in 2 weeks. Pattern shows consistent solution: test parallelization. High confidence this is a generalizable instruction.', - confidence: 0.87, - alternatives_considered: [ - { - option: 'Do not propose (confidence too low)', - score: 0.87, - rejected_reason: 'Confidence exceeds threshold of 0.80 for proposal' - } - ], - model_version: 'pattern-extractor-v1.2', - thresholds_applied: { - min_frequency: 3, - min_confidence: 0.80 - } - }, - - outcome: { - status: 'success', - result: { - proposal_id: 'prop-789', - artifact_candidate: { - title: 'GitHub Actions Test Parallelization', - description: 'Parallelize Jest tests to prevent CI timeouts' - } - }, - changes: [{ - entity_type: 'learning_proposal', - entity_id: 'prop-789', - operation: 'create', - after: { status: 'pending_review', confidence: 0.87 } - }] - }, - - rollback: { - can_rollback: true, - rollback_strategy: 'delete_proposal' - } -}); -``` - -### Causality Chain - -```typescript -// Start of workflow -const rootEventId = await auditClient.recordEvent({ - event_type: 'routing.request', - service: 'routing-service', - correlation_id: correlationId, - context: { file_path: 'src/api/auth.ts' }, - outcome: { status: 'pending' } -}); - -// Child event (caused by root) -const candidatesEventId = await auditClient.recordEvent({ - event_type: 'routing.candidates_selected', - service: 'routing-service', - correlation_id: correlationId, - parent_event_id: rootEventId, // Links to root - root_event_id: rootEventId, - outcome: { - status: 'success', - result: { total_candidates: 23, filtered: 8 } - } -}); - -// Another child event -await auditClient.recordEvent({ - event_type: 'routing.final_ranking', - service: 'routing-service', - correlation_id: correlationId, - parent_event_id: candidatesEventId, // Links to previous step - root_event_id: rootEventId, - outcome: { - status: 'success', - result: { selected: ['inst-1', 'inst-2', 'inst-3'] } - } -}); -``` - -## Event Schema - -Full schema: - -```typescript -interface AuditEvent { - // Core - event_id?: string; // Auto-generated if not provided - event_type: string; - timestamp?: Date; // Auto-generated if not provided - service: string; - - // Causality - correlation_id: string; - parent_event_id?: string; - root_event_id?: string; - - // Context - context?: { - project_id?: string; - user_id?: string; - session_id?: string; - file_path?: string; - artifact_ids?: string[]; - [key: string]: any; - }; - - // Decision data (for AI/automated decisions) - decision?: { - decision_type: string; - input: Record; - reasoning: string; - confidence: number; // 0-1 - alternatives_considered?: Array<{ - option: string; - score: number; - rejected_reason: string; - }>; - model_version?: string; - thresholds_applied?: Record; - }; - - // Outcome - outcome: { - status: 'success' | 'failure' | 'partial' | 'pending'; - result?: Record; - error?: { - code: string; - message: string; - stack?: string; - }; - changes?: Array<{ - entity_type: string; - entity_id: string; - operation: 'create' | 'update' | 'delete'; - before?: Record; - after?: Record; - diff?: string; - }>; - }; - - // Rollback support - rollback?: { - can_rollback: boolean; - rollback_strategy: string; - rollback_event_id?: string; - rolled_back_by?: string; - }; -} -``` - -## Best Practices - -### 1. Use Structured Logging - -```typescript -// ✅ Good: Structured data -await auditClient.recordEvent({ - event_type: 'routing.request', - context: { - file_path: 'src/api/auth.ts', - domains: ['backend'], - languages: ['typescript'] - }, - outcome: { status: 'success', result: { count: 5 } } -}); - -// ❌ Bad: Unstructured string -await auditClient.recordEvent({ - event_type: 'routing.request', - context: { message: 'Processing src/api/auth.ts with backend,typescript' } -}); -``` - -### 2. Always Include Reasoning for Decisions - -```typescript -// ✅ Good: Explains why -decision: { - reasoning: 'Confidence (0.87) exceeds auto-approval threshold (0.85). Pattern frequency (5) meets minimum (3). Context diversity (0.72) is acceptable.', - confidence: 0.87 -} - -// ❌ Bad: No explanation -decision: { - confidence: 0.87 -} -``` - -### 3. Capture Alternatives Considered - -```typescript -// ✅ Good: Shows decision process -alternatives_considered: [ - { option: 'Approve automatically', score: 0.87, rejected_reason: 'N/A - chosen' }, - { option: 'Send for manual review', score: 0.87, rejected_reason: 'Below manual review threshold (0.80)' }, - { option: 'Reject', score: 0.87, rejected_reason: 'Above rejection threshold (0.50)' } -] - -// ❌ Bad: No alternatives -alternatives_considered: [] -``` - -### 4. Include Enough Data for Rollback - -```typescript -// ✅ Good: Can undo -changes: [{ - entity_type: 'artifact', - entity_id: 'inst-123', - operation: 'update', - before: { status: 'draft', version: '1.0.0' }, - after: { status: 'active', version: '1.1.0' } -}] - -// ❌ Bad: Can't undo -changes: [{ - entity_type: 'artifact', - entity_id: 'inst-123', - operation: 'update' -}] -``` - -## Validation Checklist - -- [ ] All AI decisions logged with reasoning and confidence -- [ ] Correlation IDs propagated across service calls -- [ ] Parent/child relationships maintained for workflows -- [ ] Before/after states captured for all changes -- [ ] Rollback strategy defined for reversible operations -- [ ] Alternatives considered documented for key decisions -- [ ] Model versions and thresholds recorded -- [ ] Error context includes enough detail for debugging - -## Related Instructions - -- `microservices_development` - Service structure and patterns -- `event_driven_architecture` - Event bus usage -- `rest_api_design` - API logging standards diff --git a/.pongogo/instructions/devops/observability_patterns.instructions.md b/.pongogo/instructions/devops/observability_patterns.instructions.md deleted file mode 100644 index ba553ca6..00000000 --- a/.pongogo/instructions/devops/observability_patterns.instructions.md +++ /dev/null @@ -1,765 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Observability Patterns" -description: "Observability patterns for monitoring, diagnostics, and system health tracking." -applies_to: - - "**/*" -domains: - - "devops" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 1 - triggers: - keywords: - - observability - - monitoring - - prometheus - - metrics - - /metrics - - logging - - structured_logging - - winston - - tracing - - distributed_tracing - - opentelemetry - - jaeger - - correlation_ID - - X-Correlation-ID - - grafana - - dashboard - - alerting - - alert_rule - - RED_metrics - - rate_errors_duration - - log_aggregation - - loki - - span - nlp: "Observability patterns including Prometheus metrics, structured logging, distributed tracing, correlation IDs, and Grafana dashboards" -evaluation: - success_signals: - - All services expose /metrics endpoint - - Correlation IDs propagated via X-Correlation-ID header - - Logs in structured JSON format with correlation_id - - RED metrics implemented (rate, errors, duration) - - Alerts configured for high error rate and latency - failure_signals: - - Missing correlation IDs (can't trace cross-service) - - Unstructured logs (console.log, not JSON) - - "No sampling for traces (100% = performance overhead)" - - Alert fatigue (alerting on internals, not symptoms) - - No log retention policy ---- - - -# Observability Patterns for Microservices - -**Purpose**: Establish comprehensive observability for microservices enabling production monitoring, debugging, and performance analysis through metrics, logs, and traces. - -**Philosophy**: Observability is systematic prevention for production - instrument systems to understand behavior, detect issues, and diagnose problems without guessing. - ---- - -## When to Apply - -Use these observability patterns when: - -- Deploying services to production -- Debugging production issues -- Monitoring service health and performance -- Setting up alerts for critical conditions -- Analyzing request flows across services -- Optimizing performance bottlenecks - ---- - -## Quick Reference - -**Most Common Patterns**: - -**1. Add Correlation ID Middleware** (TypeScript): -```typescript -app.use((req, res, next) => { - req.correlationId = req.headers['x-correlation-id'] || uuidv4(); - res.setHeader('X-Correlation-ID', req.correlationId); - next(); -}); -``` - -**2. Structured Logging** (Winston JSON): -```typescript -logger.info('Request processed', { - correlation_id: req.correlationId, - method: req.method, - path: req.path, - duration_ms: Date.now() - startTime, -}); -``` - -**3. Prometheus RED Metrics**: -```typescript -// Rate -httpRequestsTotal.labels(method, route, status).inc(); -// Errors -if (status >= 500) httpErrors.labels(method, route).inc(); -// Duration -httpRequestDuration.labels(method, route).observe(duration); -``` - -**4. Health Check Endpoint**: -```typescript -app.get('/health', (req, res) => res.json({ status: 'healthy' })); -app.get('/ready', async (req, res) => { - const dbHealthy = await checkDatabase(); - res.status(dbHealthy ? 200 : 503).json({ ready: dbHealthy }); -}); -``` - -**5. Alert on High Error Rate** (Prometheus): -```yaml -expr: | - 100 * (rate(http_requests_total{status=~"5.."}[5m]) / - rate(http_requests_total[5m])) > 1 -``` - ---- - -## Core Principles - -- **Three Pillars**: Metrics (what's happening), Logs (why it happened), Traces (where it happened) -- **Correlation IDs**: Track requests across all services -- **Structured Logging**: JSON format for machine parsing -- **RED Metrics**: Rate, Errors, Duration for all services -- **Prometheus Format**: Standard metrics exposition -- **Sampling for Traces**: Balance detail vs overhead -- **Alert on Symptoms**: User-facing issues, not internal metrics -- **Dashboard by Service**: Each service has operational dashboard - -## Step-by-Step Guidance - -### 1. **Implement Correlation IDs** - - Generate UUID for each request at entry point - - Propagate via `X-Correlation-ID` header - - Include in all log statements - - Expected outcome: Trace requests across services - -### 2. **Add Structured Logging** - - Use winston (Node.js) or structlog (Python) - - JSON format with consistent fields - - Log levels: ERROR, WARN, INFO, DEBUG - - Expected outcome: Machine-parseable logs - -### 3. **Expose Prometheus Metrics** - - Add `/metrics` endpoint to each service - - Export RED metrics (rate, errors, duration) - - Use client libraries (prom-client, prometheus-client) - - Expected outcome: Metrics endpoint returning Prometheus format - -### 4. **Add Distributed Tracing** - - Instrument with OpenTelemetry - - Export spans to Jaeger/Zipkin - - Sample traces (1-10% in production) - - Expected outcome: Request flow visualization - -### 5. **Create Service Dashboard** - - Grafana dashboard per service - - RED metrics + health status - - Error rate trends - - Expected outcome: Operational visibility - -### 6. **Configure Alerts** - - Alert on high error rate (>1%) - - Alert on high latency (p99 >1s) - - Alert on service down - - Expected outcome: Proactive issue detection - -### 7. **Set Up Log Aggregation** - - Centralize logs (Loki, ELK) - - Retention policy (30 days) - - Search by correlation ID - - Expected outcome: Unified log view - -## Examples - -### Example 1: Correlation ID Middleware (Express) - -Propagate correlation IDs through request chain: - -```typescript -// services/routing/src/middleware/correlation.ts - -import { Request, Response, NextFunction } from 'express'; -import { v4 as uuidv4 } from 'uuid'; - -declare global { - namespace Express { - interface Request { - correlationId: string; - } - } -} - -/** - * Middleware: Add or extract correlation ID. - * - * Extracts from X-Correlation-ID header if present, - * otherwise generates new UUID. - */ -export function correlationMiddleware( - req: Request, - res: Response, - next: NextFunction -): void { - // Extract or generate correlation ID - const correlationId = req.headers['x-correlation-id'] as string || uuidv4(); - - // Attach to request - req.correlationId = correlationId; - - // Add to response headers for client tracking - res.setHeader('X-Correlation-ID', correlationId); - - next(); -} - -// Usage in service -import express from 'express'; -import { correlationMiddleware } from './middleware/correlation'; - -const app = express(); - -// Apply correlation middleware globally -app.use(correlationMiddleware); - -// All routes now have access to req.correlationId -app.post('/v1/route', async (req, res) => { - logger.info('Routing request received', { - correlation_id: req.correlationId, - request_type: req.body.type, - }); - - // When calling other services, propagate correlation ID - const response = await fetch('http://knowledge-service:3000/metadata', { - headers: { - 'X-Correlation-ID': req.correlationId, - }, - }); - - // ... -}); -``` - -**Context**: Correlation IDs enable request tracing across services -**Expected Result**: Every log statement includes correlation ID for tracking - -### Example 2: Structured Logging (Winston) - -JSON-formatted logs with consistent structure: - -```typescript -// services/routing/src/logger.ts - -import winston from 'winston'; -import { config } from './config'; - -/** - * Create structured logger. - * - * Logs in JSON format with timestamp, level, message, and metadata. - */ -export const logger = winston.createLogger({ - level: config.logLevel, - format: winston.format.combine( - winston.format.timestamp(), - winston.format.errors({ stack: true }), - winston.format.json() - ), - defaultMeta: { - service: 'routing-service', - environment: config.nodeEnv, - }, - transports: [ - new winston.transports.Console(), - ], -}); - -// Usage in application code -import { logger } from './logger'; - -// Info log -logger.info('Routing request completed', { - correlation_id: req.correlationId, - request_type: 'file_path', - matches_found: 3, - duration_ms: 45, -}); - -// Error log with stack trace -try { - const result = await processRequest(request); -} catch (error) { - logger.error('Request processing failed', { - correlation_id: req.correlationId, - error: error.message, - stack: error.stack, - request_type: request.type, - }); - throw error; -} - -// Debug log (only in development) -logger.debug('Pattern matching details', { - correlation_id: req.correlationId, - patterns_checked: 25, - pattern_matches: [ - { pattern: 'services/**/*.ts', confidence: 0.95 }, - { pattern: '**/*.ts', confidence: 0.85 }, - ], -}); - -// Example log output (JSON) -{ - "timestamp": "2025-10-27T10:30:45.123Z", - "level": "info", - "message": "Routing request completed", - "service": "routing-service", - "environment": "production", - "correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", - "request_type": "file_path", - "matches_found": 3, - "duration_ms": 45 -} -``` - -**Context**: Structured logs enable log aggregation and querying -**Expected Result**: All logs in consistent JSON format - -### Example 3: Prometheus Metrics (Node.js) - -Expose RED metrics (Rate, Errors, Duration): - -```typescript -// services/routing/src/metrics.ts - -import promClient from 'prom-client'; -import express from 'express'; - -// Create registry -const register = new promClient.Registry(); - -// Default metrics (CPU, memory, etc.) -promClient.collectDefaultMetrics({ register }); - -// Custom metrics - -// Counter: Total requests -const httpRequestsTotal = new promClient.Counter({ - name: 'http_requests_total', - help: 'Total HTTP requests', - labelNames: ['method', 'path', 'status'], - registers: [register], -}); - -// Histogram: Request duration -const httpRequestDuration = new promClient.Histogram({ - name: 'http_request_duration_seconds', - help: 'HTTP request duration in seconds', - labelNames: ['method', 'path', 'status'], - buckets: [0.01, 0.05, 0.1, 0.5, 1, 2, 5], - registers: [register], -}); - -// Gauge: Active requests -const httpRequestsInProgress = new promClient.Gauge({ - name: 'http_requests_in_progress', - help: 'HTTP requests currently in progress', - labelNames: ['method', 'path'], - registers: [register], -}); - -// Counter: Routing matches -const routingMatchesTotal = new promClient.Counter({ - name: 'routing_matches_total', - help: 'Total routing matches returned', - labelNames: ['request_type'], - registers: [register], -}); - -/** - * Middleware: Record metrics for all requests. - */ -export function metricsMiddleware( - req: express.Request, - res: express.Response, - next: express.NextFunction -): void { - const start = Date.now(); - - // Track in-progress - httpRequestsInProgress.labels(req.method, req.path).inc(); - - // On response finish - res.on('finish', () => { - const duration = (Date.now() - start) / 1000; - - // Record request - httpRequestsTotal.labels(req.method, req.path, String(res.statusCode)).inc(); - - // Record duration - httpRequestDuration - .labels(req.method, req.path, String(res.statusCode)) - .observe(duration); - - // Decrement in-progress - httpRequestsInProgress.labels(req.method, req.path).dec(); - }); - - next(); -} - -/** - * Metrics endpoint for Prometheus scraping. - */ -export async function metricsEndpoint( - req: express.Request, - res: express.Response -): Promise { - res.set('Content-Type', register.contentType); - res.end(await register.metrics()); -} - -// Usage in service -import express from 'express'; -import { metricsMiddleware, metricsEndpoint } from './metrics'; - -const app = express(); - -// Apply metrics middleware -app.use(metricsMiddleware); - -// Expose metrics endpoint -app.get('/metrics', metricsEndpoint); - -// Record custom metrics in business logic -import { routingMatchesTotal } from './metrics'; - -async function route(request: RoutingRequest): Promise { - const matches = await findMatches(request); - - // Record custom metric - routingMatchesTotal.labels(request.type).inc(matches.length); - - return { instructions: matches }; -} -``` - -**Context**: Prometheus metrics enable performance monitoring and alerting -**Expected Result**: `/metrics` endpoint returns Prometheus-format metrics - -### Example 4: Distributed Tracing (OpenTelemetry) - -Instrument services for request tracing: - -```typescript -// services/routing/src/tracing.ts - -import { NodeSDK } from '@opentelemetry/sdk-node'; -import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'; -import { JaegerExporter } from '@opentelemetry/exporter-jaeger'; -import { Resource } from '@opentelemetry/resources'; -import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions'; - -/** - * Initialize OpenTelemetry tracing. - * - * Auto-instruments Express, HTTP, and database clients. - */ -export function initTracing(): NodeSDK { - const exporter = new JaegerExporter({ - endpoint: process.env.JAEGER_ENDPOINT || 'http://jaeger:14268/api/traces', - }); - - const sdk = new NodeSDK({ - resource: new Resource({ - [SemanticResourceAttributes.SERVICE_NAME]: 'routing-service', - [SemanticResourceAttributes.SERVICE_VERSION]: '1.0.0', - [SemanticResourceAttributes.DEPLOYMENT_ENVIRONMENT]: process.env.NODE_ENV, - }), - traceExporter: exporter, - instrumentations: [ - getNodeAutoInstrumentations({ - // Auto-instrument HTTP, Express, pg, etc. - '@opentelemetry/instrumentation-http': {}, - '@opentelemetry/instrumentation-express': {}, - '@opentelemetry/instrumentation-pg': {}, - }), - ], - }); - - sdk.start(); - - return sdk; -} - -// Manual span creation for custom operations -import { trace } from '@opentelemetry/api'; - -async function findMatchingInstructions( - type: string, - value: string -): Promise { - const tracer = trace.getTracer('routing-service'); - - // Create custom span - return tracer.startActiveSpan('findMatchingInstructions', async (span) => { - span.setAttribute('request.type', type); - span.setAttribute('request.value_length', value.length); - - try { - const matches = await performMatching(type, value); - - span.setAttribute('matches.found', matches.length); - span.setStatus({ code: 0 }); // OK - - return matches; - } catch (error) { - span.setStatus({ - code: 2, // ERROR - message: error.message, - }); - span.recordException(error); - throw error; - } finally { - span.end(); - } - }); -} - -// Usage in index.ts -import { initTracing } from './tracing'; - -// Initialize tracing before starting server -const sdk = initTracing(); - -// Graceful shutdown -process.on('SIGTERM', async () => { - await sdk.shutdown(); -}); -``` - -**Context**: Distributed tracing visualizes request flow across services -**Expected Result**: Traces exported to Jaeger for analysis - -### Example 5: Grafana Dashboard Configuration - -Service dashboard with RED metrics: - -```json -{ - "dashboard": { - "title": "Routing Service", - "tags": ["observability", "routing"], - "timezone": "browser", - "panels": [ - { - "title": "Request Rate (req/s)", - "type": "graph", - "targets": [ - { - "expr": "rate(http_requests_total{service=\"routing-service\"}[5m])", - "legendFormat": "{{method}} {{path}}" - } - ] - }, - { - "title": "Error Rate (%)", - "type": "graph", - "targets": [ - { - "expr": "100 * (rate(http_requests_total{service=\"routing-service\",status=~\"5..\"}[5m]) / rate(http_requests_total{service=\"routing-service\"}[5m]))", - "legendFormat": "Error Rate" - } - ], - "alert": { - "conditions": [ - { - "evaluator": { - "params": [1], - "type": "gt" - }, - "query": { - "params": ["A", "5m", "now"] - } - } - ], - "name": "High Error Rate", - "message": "Routing service error rate above 1%" - } - }, - { - "title": "Request Duration (p50, p95, p99)", - "type": "graph", - "targets": [ - { - "expr": "histogram_quantile(0.50, rate(http_request_duration_seconds_bucket{service=\"routing-service\"}[5m]))", - "legendFormat": "p50" - }, - { - "expr": "histogram_quantile(0.95, rate(http_request_duration_seconds_bucket{service=\"routing-service\"}[5m]))", - "legendFormat": "p95" - }, - { - "expr": "histogram_quantile(0.99, rate(http_request_duration_seconds_bucket{service=\"routing-service\"}[5m]))", - "legendFormat": "p99" - } - ] - }, - { - "title": "Active Requests", - "type": "graph", - "targets": [ - { - "expr": "http_requests_in_progress{service=\"routing-service\"}", - "legendFormat": "{{method}} {{path}}" - } - ] - }, - { - "title": "Routing Matches", - "type": "graph", - "targets": [ - { - "expr": "rate(routing_matches_total{service=\"routing-service\"}[5m])", - "legendFormat": "{{request_type}}" - } - ] - } - ] - } -} -``` - -**Context**: Grafana dashboards provide operational visibility -**Expected Result**: Real-time service health monitoring - -## Validation Checklist - -Before considering observability complete: - -- [ ] Correlation ID middleware added to all services -- [ ] Structured logging with winston/structlog -- [ ] All logs include correlation_id field -- [ ] Prometheus `/metrics` endpoint exposed -- [ ] RED metrics implemented (rate, errors, duration) -- [ ] Custom business metrics added -- [ ] Distributed tracing with OpenTelemetry -- [ ] Traces exported to Jaeger/Zipkin -- [ ] Grafana dashboard created per service -- [ ] Alerts configured for high error rate -- [ ] Alerts configured for high latency -- [ ] Log aggregation set up (Loki/ELK) -- [ ] Retention policies configured -- [ ] Runbooks linked from alerts - -## Common Pitfalls - -### Pitfall 1: Missing Correlation IDs - -- ❌ **Problem**: Can't trace requests across services -- **Why it happens**: Not propagating correlation ID in headers -- ✅ **Solution**: Add correlation middleware, propagate in all service calls -- **Example**: Debugging cross-service issue requires manual correlation - -### Pitfall 2: Unstructured Logs - -- ❌ **Problem**: Logs not parseable, can't search/aggregate -- **Why it happens**: Using console.log instead of structured logger -- ✅ **Solution**: Use winston/structlog with JSON format -- **Example**: "Error processing request" - no context, can't filter - -### Pitfall 3: No Sampling for Traces - -- ❌ **Problem**: Tracing overhead kills performance -- **Why it happens**: Tracing 100% of requests in production -- ✅ **Solution**: Sample 1-10% of traces in production -- **Example**: Tracing adds 50ms to every request - -### Pitfall 4: Alerting on Everything - -- ❌ **Problem**: Alert fatigue, ignore critical alerts -- **Why it happens**: Alerting on internal metrics, not symptoms -- ✅ **Solution**: Alert only on user-facing issues (high error rate, latency) -- **Example**: CPU alert fires constantly, team ignores it - -### Pitfall 5: No Log Retention Policy - -- ❌ **Problem**: Log storage grows unbounded, expensive -- **Why it happens**: Not configuring retention -- ✅ **Solution**: 30-day retention, archive critical logs -- **Example**: 1TB of logs after 6 months - -## Edge Cases - -### Edge Case 1: High-Cardinality Metrics - -**When**: Metric labels have many unique values (user IDs, URLs) -**Approach**: -- Avoid high-cardinality labels in Prometheus -- Use aggregation (error count, not per-user) -- For detailed analysis, use logs/traces instead -**Example**: Label by endpoint, not by full URL path - -### Edge Case 2: PII in Logs - -**When**: Personal identifiable information in log messages -**Approach**: -- Sanitize sensitive data before logging -- Hash or redact user IDs, emails, tokens -- Document what's safe to log -**Example**: Log user_id hash, not email address - -### Edge Case 3: Distributed Tracing Sampling - -**When**: Need to trace specific high-value requests -**Approach**: -- Sample 100% for canary requests -- Sample 100% for errors -- Sample 1-10% for normal traffic -**Example**: Always trace requests with debug header - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| Can't trace cross-service requests | Missing correlation IDs | Add correlation middleware, propagate headers | -| Logs not searchable | Unstructured format | Use winston/structlog with JSON | -| Prometheus scrape fails | No /metrics endpoint | Add metrics endpoint | -| Tracing overhead high | No sampling | Sample 1-10% in production | -| Too many alerts | Alerting on internals | Alert on user-facing symptoms only | -| Log storage expensive | No retention policy | Configure 30-day retention | -| Missing traces for errors | Sampling drops errors | Always sample error traces | -| Dashboard shows no data | Incorrect Prometheus query | Verify metric names, labels | - -## Related Instructions - -**Core Integration**: -- [Microservices Development](../development_standards/microservices_development.instructions.md) - Health checks and metrics basics for services -- [Performance Optimization](./performance_optimization.instructions.md) - Using metrics to identify bottlenecks, profiling with observability data -- [Error Handling](../development_standards/error_handling.instructions.md) - What to log in error scenarios, structured error logging - -**Deployment & Configuration**: -- [CI/CD Pipelines](./ci_cd_pipelines.instructions.md) - Metrics collection in deployment pipelines, health checks before release -- [Docker Compose Orchestration](../development_standards/docker_compose_orchestration.instructions.md) - Local observability stack setup (Prometheus, Grafana, Jaeger) -- [Environment Configuration](../quality/environment_configuration.instructions.md) - Observability service URLs, sampling rates, log levels - -**Security & Quality**: -- [Security Hardening](./security_hardening.instructions.md) - What NOT to log (secrets, PII), secure metrics endpoints -- [Testing Standards](../quality/testing_standards.instructions.md) - Testing observability integration, validating metrics accuracy - ---- - -**Success Criteria**: All services expose /metrics endpoint, logs are structured JSON with correlation IDs, distributed tracing configured, Grafana dashboards operational, alerts configured for high error rate and latency. - -**Confidence Check**: Can you trace a request across all services using correlation ID? Are all logs in JSON format? Does Grafana show RED metrics for each service? Do alerts fire for high error rates? diff --git a/.pongogo/instructions/documentation/instruction_file_compliance.instructions.md b/.pongogo/instructions/documentation/instruction_file_compliance.instructions.md deleted file mode 100644 index 862c941f..00000000 --- a/.pongogo/instructions/documentation/instruction_file_compliance.instructions.md +++ /dev/null @@ -1,394 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Instruction File Compliance Framework" -description: "Ensures agents READ routed instructions rather than executing from memory, preventing the 'Instruction Execution from Memory' anti-pattern." -applies_to: - - "**/*.md" - - "**/*.instructions.md" -domains: - - "compliance" - - "agentic_workflows" -priority: "P0" -pongogo_version: "2026-02-13" -source: "Original" - -id: documentation_instruction_file_compliance -enforcement: - scope: session - blocked_tools: - - mutating - blocked_until: - - action_type: read_instruction -routing: - priority: 1 - description: "Compliance framework ensuring agents read instruction files before executing procedural actions" - triggers: - keywords: - - instruction_compliance - - routing_compliance - - read_instruction - - follow_checklist - - procedural_instruction - - mandatory_read - - execute_from_memory - - mental_checklist - - compliance_gate - - read_before_execute - - skipped_steps - - checklist_verification - nlp: "Ensuring agents read routed instructions rather than executing from memory to prevent step skipping and compliance failures" -evaluation: - success_signals: - - Agent calls Read tool on instruction file before executing procedural actions - - Completion claims cite step numbers from the actual instruction file - - Agent verifies each mandatory step against the file before claiming completion - - Compliance gate questions answered before procedural execution - failure_signals: - - Agent executes procedural steps from memory without reading instruction file - - Completion summary uses generic descriptions instead of step-number citations - - Routing surfaces instruction but agent acknowledges without reading - - Agent claims "I know what the checklist says" instead of reading it ---- - - -# Instruction File Compliance Framework - -**Purpose**: Ensure routed instructions are READ, not executed from memory, preventing the "Instruction Execution from Memory" anti-pattern that defeats the routing system. - -**Philosophy**: Routing discovery does not equal instruction compliance. Surfacing an instruction is only half the solution. Enforcement between "instruction surfaced" and "instruction followed" is the other half. - ---- - -## When to Apply - -This instruction applies when: - -- **Scenario 1**: Routing surfaces an instruction file with procedural content (checklists, multi-step processes) -- **Scenario 2**: About to execute any multi-step workflow (issue closure, learning loop, RCA, etc.) -- **Scenario 3**: Claiming completion of a procedural task ("learning loop conducted", "checklist complete") -- **Scenario 4**: Status transition that requires checklist verification -- **Scenario 5**: Any situation where you "know" what an instruction file says without reading it - ---- - -## COMPLIANCE GATE (BLOCKING - NOT ADVISORY) - -**BEFORE EXECUTING ANY PROCEDURAL INSTRUCTION, ANSWER THESE QUESTIONS**: - -1. **Have I READ (not recalled) this instruction file?** - - YES: Proceed - - NO: **STOP. Read the instruction file NOW.** - -2. **Am I about to execute from memory?** - - YES: **STOP. This is the "Instruction Execution from Memory" anti-pattern** - - NO: Proceed - -3. **Can I cite step numbers from the file?** - - YES: You have read it. Proceed. - - NO: You have not read it. **STOP and read it.** - ---- - -## Quick Reference - -**Key Decision Criteria**: - -- **Procedural Instruction**: Has numbered steps, checklist, or multi-phase process. MUST READ BEFORE EXECUTING -- **Reference Instruction**: API patterns, code snippets, configuration. Can reference as needed -- **Routing Surfaced**: Routing recommends an instruction. READ IT, don't acknowledge and proceed - -**Compliance Self-Check** (ask before claiming completion): -``` -1. Did I READ the instruction file? (not recall from memory) -2. Can I cite step numbers for what I completed? -3. Did I verify completion against the file's checklist? -``` - -**Anti-Pattern Detection**: -``` -If you find yourself thinking: - "I know what the checklist says..." - "The learning loop is: review, extract, capture..." - "Issue closure requires approval and then..." - -STOP. This is "mental checklist execution." Read the actual file. -``` - ---- - -## Core Principles - -- **Routing Discovery is not Compliance**: Surfacing an instruction does not mean it will be followed -- **READ Before Execute**: Never assume knowledge of procedural instruction content -- **Cite Step Numbers**: Completion claims must reference specific steps from the file -- **Compliance Gates are not Reminders**: Gates enforce behavior; reminders are ignored -- **Prevention over Detection**: Catch compliance gaps before user detection - ---- - -## Enforcement Mechanism - -**HARD REQUIREMENT**: The compliance gate above is **BLOCKING**, not advisory. - -**Mandatory Read Tool Call**: -- Before ANY procedural action (closure, learning loop, RCA, etc.), you MUST call the `Read` tool on the relevant instruction file -- If the instruction file references additional documents, you MUST Read those too -- The Read tool call creates an **audit trail** in your transcript - -**Compliance Evidence**: -- If user asks "did you follow the checklist?" your transcript MUST contain Read tool calls for the checklist -- If Read tool call is NOT in transcript, compliance failed -- "I know what the checklist says" is NOT evidence. The Read tool call IS evidence. - -**Step Citation Requirement**: -- Completion comments MUST cite step numbers from the actual file -- Format: "Step 1: [action] done", "Step 2: [action] done", etc. -- Generic summaries without step numbers indicate memory-based execution - ---- - -## Step-by-Step Guidance - -### 1. Recognize Procedural Instructions - -**Action**: Identify instruction files that require full reading before execution. - -**Procedural Instruction Indicators**: -- Contains numbered steps (Step 1, Step 2, Step 3...) -- Has checklist format (checkbox items) -- Describes multi-phase process (Phase 1, Phase 2, Phase 3) -- References "mandatory" steps or requirements -- Line count > 100 (substantial procedural content) - -**Expected outcome**: You can distinguish procedural instructions from reference instructions. - -### 2. Execute Compliance Gate - -**Action**: Before executing any procedural instruction, pass the compliance gate. - -**Compliance Gate Questions**: -1. Have I READ (not recalled) this instruction file? -2. Am I about to execute from memory? -3. Can I cite step numbers from the file? - -**If ANY answer is wrong**: -- STOP execution -- Read the full instruction file -- Re-attempt compliance gate - -### 3. Execute with File Reference - -**Action**: Keep the instruction file content visible during execution. - -**Process**: -1. Read the instruction file fully -2. Note total steps/phases -3. Execute step by step, checking each against the file -4. Mark completion as you go (not at end) - -**DO NOT**: -- Execute from memory after reading once -- Skip steps because "I remember what to do" -- Batch-mark completions at the end - -**Success indicator**: You can cite the step number you are currently executing. - -### 4. Verify Completion Against File - -**Action**: After execution, verify against the instruction file's checklist. - -**Verification Process**: -1. Re-read the instruction file's validation checklist (if present) -2. Confirm each mandatory step was executed (not just "covered") -3. Note any steps that were implicit vs explicit -4. If gaps found: execute missing steps before claiming completion - -**Expected outcome**: You can provide evidence for each mandatory step. - -### 5. Cite Step Numbers in Completion Claims - -**Action**: When claiming completion, reference specific steps from the file. - -**Good Completion Claim**: -``` -Learning loop complete: -- Step 1 (Review): Completed, reviewed deliverables -- Step 2 (Extract): Completed, identified 2 patterns -- Step 3 (Capture): Completed, PI created -- Step 4 (Document): Completed, decision recorded -- Step 5 (Create artifact): Completed, work log entry added -- Step 6 (Institutionalize): Completed, Pattern Library updated - -Evidence: Can cite step numbers from learning_loop_execution.instructions.md -``` - -**Bad Completion Claim**: -``` -Learning loop complete - reviewed work, extracted patterns, updated knowledge. -``` - ---- - -## Declarative Enforcement Engine (Preceptor v0.2.0) - -The compliance framework is backed by Pongogo's declarative enforcement engine (the "preceptor"), which automatically blocks mutating tools until compliance requirements are met. - -**Enforcement action types**: - -| action_type | What it enforces | How it is fulfilled | -|---|---|---| -| `read_instruction` | Agent must READ the instruction file | Agent calls `Read` tool on the instruction file | -| `read_file` | Agent must read a specific file | Agent calls `Read` on the specified file path | -| `call_mcp_tool` | Agent must call a specific MCP tool | Agent calls the named MCP tool | -| `process_checklist` | Agent must process a checklist | Agent works through checklist items | -| `approval_required` | User approval required | User approves the action | - -**`call_mcp_tool` enforcement** (new in Preceptor v0.2.0): - -Some procedural instructions require calling an MCP tool as the compliance-critical action. For example, a user guidance capture instruction might require calling `log_user_guidance`. Reading the instruction alone is insufficient. - -```yaml -# Example: enforcement that requires an MCP tool call -enforcement: - scope: session - blocked_tools: - - mutating - blocked_until: - - action_type: call_mcp_tool - tool_name: "log_user_guidance" -``` - -The preceptor validates both tool name matching and optional required arguments. This extends compliance beyond "read before execute" to "act before proceed." - ---- - -## Examples - -### Example 1: Compliant Procedural Execution - -**Context**: Closing an issue after completing work. - -**Compliant Execution**: -``` -Pre-Closure Compliance Check: -1. Have I READ issue_closure.instructions.md? YES - Read full file -2. Am I executing from memory? NO - Following file directly -3. Can I cite step numbers? YES - Currently on Step 5 - -Execution Log: -Step 1: Deliverables verified -Step 2: Documentation updated -Step 3: Checkboxes updated (real-time) -Step 4: Acceptance criteria met -Step 5: Learning loop conducted -Step 6: Cross-issue impacts checked -Step 7: Completion comment posted -Step 8: Status set to Ready for Review -``` - -**Expected Result**: All steps executed, user approval obtained, zero compliance gaps. - -### Example 2: Detecting Mental Checklist Execution - -**Context**: Agent about to execute a learning loop. - -**Non-Compliant (Mental Checklist)**: -``` -I'll conduct the learning loop now: -- Review what was accomplished -- Extract patterns -- Update knowledge systems -``` - -**Problem**: No file reference, no step numbers, executing from memory. - -**Compliant (File-Based)**: -``` -Let me read learning_loop_execution.instructions.md first. -[Reads file] - -Now executing learning loop per instruction file: - -Step 1 (Review): What was accomplished? -- Created compliance instruction file -- Updated Pattern Library - -Step 6 (Institutionalize): What knowledge systems updated? -- Pattern Library: Added 3 patterns -- Strategic Insights: Added 1 insight -``` - ---- - -## Validation Checklist - -**Before claiming procedural instruction completion**: - -- [ ] Compliance gate passed (3 questions answered YES) -- [ ] Instruction file read in full (not recalled from memory) -- [ ] Step numbers citable for completed work -- [ ] Each mandatory step verified against file -- [ ] No implicit execution (explicit verification for each step) -- [ ] Completion evidence tied to specific steps - ---- - -## Common Pitfalls - -### Pitfall 1: Instruction Execution from Memory - -- **Problem**: Agent acknowledges instruction file exists, executes from memory, misses steps -- **Why it happens**: Agent assumes it "knows" what the checklist requires -- **Solution**: Always read file before execution, cite step numbers - -### Pitfall 2: Routing Discovery Theater - -- **Problem**: Routing surfaces correct instruction, agent acknowledges but does not read -- **Why it happens**: Routing designed for discovery, not compliance verification -- **Solution**: Treat routing recommendations as "READ NOW" commands, not "FYI" notices - -### Pitfall 3: Mental Checklist with False Precision - -- **Problem**: Agent creates detailed completion summary that hides missed steps -- **Why it happens**: Memory-based execution feels systematic but is not verified -- **Solution**: Require step-number citations, verify against actual file - -### Pitfall 4: Batch Compliance Verification - -- **Problem**: Verifying compliance at end instead of during execution -- **Why it happens**: Efficiency bias, belief that "I'll check at the end" -- **Solution**: Real-time step verification, mark as you go - ---- - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| User asks "did you follow checklist?" | Compliance gap detected | Re-read file, execute missing steps | -| Cannot cite step numbers | Memory-based execution | Read file again, note step numbers | -| Missed mandatory step | Skipped compliance gate | Execute compliance gate before next procedure | -| False completion claim | Mental checklist execution | Verify each step against actual file | -| User catches gaps repeatedly | Systemic compliance failure | Review this instruction, add to workflow | - ---- - -## Integration with Routing System - -**Critical Insight**: The routing system's value depends on this compliance framework. - -**Without Compliance**: -- Routing surfaces correct instructions. Agent acknowledges. Executes from memory. Steps missed. -- Result: Routing investment produces no outcome (discovery theater) - -**With Compliance**: -- Routing surfaces correct instructions. Agent reads file. Executes from file. Steps completed. -- Result: Routing investment produces correct behavior (discovery to compliance to outcome) - -**Strategic Priority**: This compliance framework is P0 because it protects the routing system investment. - ---- - -**Success Criteria**: Agents can execute procedural instructions with zero user-detected compliance gaps by reading files before execution and citing step numbers in completion claims. - -**Confidence Check**: "Can I cite the step number I'm currently executing from the instruction file?" If YES, compliant. If NO, stop and read the file. diff --git a/.pongogo/instructions/documentation/instruction_file_creation.instructions.md b/.pongogo/instructions/documentation/instruction_file_creation.instructions.md deleted file mode 100644 index e5a183bf..00000000 --- a/.pongogo/instructions/documentation/instruction_file_creation.instructions.md +++ /dev/null @@ -1,599 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Instruction File Creation Standards" -description: "Standards for creating new instruction files with proper structure and metadata." -applies_to: - - "**/*" -domains: - - "documentation" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 0 - triggers: - keywords: - - instruction_file - - create_instruction - - instruction_template - - YAML_frontmatter - - evaluation_criteria - - success_signals - - failure_signals - - prompt_engineering - - instruction_standards - nlp: "Creating instruction files with proper structure, evaluation criteria, and prompt engineering best practices" -evaluation: - success_signals: - - YAML frontmatter includes evaluation section with success/failure signals - - Purpose and Philosophy statements are one sentence each - - Quick Reference section provides 3-5 actionable patterns - - Examples demonstrate exact structure (not just rules) - - Step-by-step guidance uses numbered steps with expected outcomes - failure_signals: - - Missing evaluation criteria (no success/failure signals) - - Abstract principles without concrete examples - - Prose paragraphs instead of structured lists/steps - - Vague terms without explicit definitions - - Missing "When to Apply" scenarios ---- - - -# Instruction File Creation Standards - -**Purpose**: Define standards for creating instruction files that produce reliable agent behavior through clear structure, evaluation criteria, and prompt engineering best practices. - -**Philosophy**: Instructions must be testable - every instruction file needs explicit success and failure signals that enable compliance verification without human judgment. - ---- - -## When to Apply - -This instruction applies when: - -- **Scenario 1**: Creating new instruction files for any domain -- **Scenario 2**: Reviewing existing instructions for quality improvement -- **Scenario 3**: Agent needs guidance on what makes a good instruction file -- **Scenario 4**: Converting informal knowledge into structured instruction files -- **Scenario 5**: Evaluating instruction file quality against standards - ---- - -## Quick Reference - -**Essential Instruction File Components**: - -**1. YAML Frontmatter Template**: -```yaml ---- -title: "Human-Readable Title" -description: "One-sentence description of purpose" -applies_to: - - "**/*.ts" # Glob patterns for auto-discovery -domains: - - "domain_name" -priority: "P0" # P0=Critical, P1=Core, P2=Standard, P3=Optional -patterns: - - "pattern_name" -related_instructions: - - "../path/to/related.instructions.md" -evaluation: - success_signals: - - Observable behavior when instruction is followed correctly - - Another measurable outcome indicating success - failure_signals: - - Observable behavior when instruction is NOT followed - - Anti-pattern that indicates non-compliance -routing: - priority: 1 - triggers: - keywords: - - snake_case_keywords - nlp: "Natural language description of when this applies" ---- -``` - -**2. Document Structure Template**: -```markdown -# Title - -**Purpose**: One sentence describing what this instruction achieves. - -**Philosophy**: One sentence describing the underlying principle. - ---- - -## When to Apply -- Scenario 1: [specific trigger condition] -- Scenario 2: [another trigger condition] - ---- - -## Quick Reference -[3-5 most common patterns with code examples] - ---- - -## Core Principles -- Principle 1 (no more than 5) - -## Step-by-Step Guidance -### 1. First Step -[Action with expected outcome] - -## Examples -### Example 1: [Scenario Name] -[Complete working example] - -## Validation Checklist -- [ ] Checkable item - -## Common Pitfalls -### Pitfall 1: [Name] -- Problem, Why it happens, Solution -``` - -**3. Evaluation Criteria Pattern**: -```yaml -evaluation: - success_signals: - - [What you observe when instruction is followed] - - [Measurable outcome, not subjective assessment] - - [Specific artifact or behavior, not vague quality] - failure_signals: - - [What you observe when instruction is NOT followed] - - [Anti-pattern that indicates non-compliance] - - [Concrete failure mode, not absence of success] -``` - -**4. Example Quality Standard**: -```markdown -### Example 1: [Descriptive Scenario Name] - -**Context**: [When/why this example applies] - -**Scenario**: [Specific situation being demonstrated] - -[Code block or structured content showing exact format] - -**Expected Result**: [What happens when example is applied] -``` - -**5. Keywords Convention**: -```yaml -keywords: - - snake_case_only # Correct: enables n-gram matching - - multi_word_concept # Correct: "multi word concept" matches - - single-word # WRONG: hyphens break matching - - "two words" # WRONG: spaces break matching -``` - ---- - -## Core Principles - -- **Evaluation-First Design**: Every instruction must have explicit success and failure signals before writing content -- **Colleague Test Clarity**: Instructions must be executable by someone with no prior context -- **Show Don't Tell**: Examples demonstrate exact structure, not abstract rules -- **Machine-Readable Structure**: Use numbered steps, checklists, and code blocks (not prose paragraphs) -- **Progressive Disclosure**: Essential patterns in Quick Reference, detail in Step-by-Step - ---- - -## Step-by-Step Guidance - -### 1. Define Evaluation Criteria First - -Before writing any content, define what success and failure look like. - -**Action**: Write `evaluation` section in YAML frontmatter with 5 success signals and 5 failure signals - -**Success Signal Criteria**: -- Observable (can see it happened) -- Specific (not vague like "good quality") -- Measurable (can count or verify) -- Actionable (tells you what to check) - -**Failure Signal Criteria**: -- Concrete anti-patterns (not just "didn't follow instruction") -- Common mistakes (things that actually happen) -- Detectable (can identify when they occur) - -**Expected outcome**: Clear criteria that enable automated compliance checking - -### 2. Write Purpose and Philosophy Statements - -**Action**: Create exactly one sentence for each - -**Purpose Format**: "Define/Establish/Ensure [what] for [outcome]" -**Philosophy Format**: "[Core principle] - [why it matters]" - -**Examples**: -- Purpose: "Ensure all validation produces deterministic results with 100% pass rate requirement." -- Philosophy: "Agents require binary pass/fail signals, not probabilistic thresholds." - -**Expected outcome**: Reader understands intent in two sentences - -### 3. Define "When to Apply" Scenarios - -**Action**: List 3-5 specific scenarios where this instruction should trigger - -**Scenario Format**: "**Scenario N**: [Specific condition or trigger]" - -**Guidelines**: -- Be specific (not "when writing code") -- Include both common and edge cases -- Match routing keywords to scenarios - -**Expected outcome**: Agent knows exactly when to apply this instruction - -### 4. Create Quick Reference Section - -**Action**: Extract 3-5 most common patterns as minimal, runnable examples - -**Guidelines**: -- Each pattern: 5-15 lines of code maximum -- Include language tags on code blocks -- No explanatory prose (save for Step-by-Step) -- Number each pattern for reference - -**Expected outcome**: Agent finds common patterns in <5 seconds - -### 5. Write Step-by-Step Guidance with Expected Outcomes - -**Action**: Create numbered steps, each with explicit expected outcome - -**Step Format**: -```markdown -### N. Step Title - -[Action description in imperative mood] - -- Specific action 1 -- Specific action 2 - -**Expected outcome**: [What should exist after this step] -``` - -**Guidelines**: -- Use imperative mood ("Create file" not "You should create") -- Include expected outcome for every step -- Keep steps atomic (one action per step) - -**Expected outcome**: Agent can execute step-by-step without interpretation - -### 6. Provide Concrete Examples - -**Action**: Include 2-3 complete, working examples - -**Example Requirements**: -- Show exact format (not description of format) -- Include context and scenario -- State expected result -- Cover common case + edge case - -**Expected outcome**: Agent can copy/adapt examples directly - -### 7. Add Validation Checklist - -**Action**: Create machine-readable checklist with markdown checkboxes - -**Checklist Format**: -```markdown -## Validation Checklist - -- [ ] Evaluation criteria defined in frontmatter -- [ ] Purpose is one sentence -- [ ] Philosophy is one sentence -- [ ] Quick Reference has 3-5 patterns -- [ ] Examples show exact structure -- [ ] All steps have expected outcomes -``` - -**Expected outcome**: Agent can verify completion programmatically - -### 8. Document Common Pitfalls - -**Action**: List 3-5 common mistakes with problem, cause, and solution - -**Pitfall Format**: -```markdown -### Pitfall N: [Name] - -- **Problem**: [What goes wrong] -- **Why it happens**: [Root cause] -- **Solution**: [How to fix or prevent] -``` - -**Expected outcome**: Agent avoids documented mistakes - -### 9. Add Enforcement Frontmatter (Procedural Instructions Only) - -**Action**: For instructions with numbered steps, checklists, or multi-phase processes, add an `enforcement:` block to the YAML frontmatter. This enables Pongogo's preceptor (v0.2.0) to automatically block mutating tools until compliance requirements are met. - -**Enforcement Template**: -```yaml -enforcement: - scope: session # session or action - blocked_tools: - - mutating # Tool categories: mutating, reading, executing - blocked_until: - - action_type: read_instruction # Must read this instruction file -``` - -**Supported `action_type` values**: - -| action_type | Purpose | Required fields | -|---|---|---| -| `read_instruction` | Agent must read this instruction file | None (implicit) | -| `read_file` | Agent must read a specific file | `file: "path/to/file"` | -| `call_mcp_tool` | Agent must call a specific MCP tool | `tool_name: "tool_name"`, optional `required_args: {}` | -| `process_checklist` | Agent must process a checklist | None | -| `approval_required` | User approval required | None | - -**`call_mcp_tool` Example** (when instruction requires an MCP tool call): -```yaml -enforcement: - scope: session - blocked_tools: - - mutating - blocked_until: - - action_type: call_mcp_tool - tool_name: "log_user_guidance" - required_args: # Optional: args the tool call must include - guidance_type: "explicit" -``` - -**When to add enforcement**: -- Instruction has numbered steps that MUST be followed in order -- Skipping steps leads to measurable failure (documented incidents, RCAs) -- Multi-step processes where agents tend to execute from memory -- Instruction requires a specific MCP tool call as its core action - -**When NOT to add enforcement**: -- Reference/advisory instructions (architecture principles, naming conventions) -- Behavioral instructions (collaboration preferences, communication style) -- Informational instructions without mandatory workflow - -**Expected outcome**: Preceptor automatically enforces compliance before agents can take mutating actions - ---- - -## Examples - -### Example 1: Minimal Instruction File - -**Context**: Creating a simple instruction file for a single concept - -**Scenario**: New instruction for commit message formatting - -```yaml ---- -title: "Commit Message Format" -description: "Context-rich commit messages with model attribution" -applies_to: - - "**/*" -domains: - - "software_engineering" -priority: "P1" -patterns: - - "context_rich_commits" -evaluation: - success_signals: - - Summary line 50-72 chars in imperative mood - - What Changed and Why sections present - - Model attribution footer included - failure_signals: - - Vague summary like "update files" - - Missing Why section - - No model attribution -routing: - priority: 1 - triggers: - keywords: - - commit_message - - git_commit - nlp: "Creating commit messages with context and attribution" ---- - -# Commit Message Format - -**Purpose**: Create commit messages that provide context for future archaeology. - -**Philosophy**: Commit messages are for future readers - document why, not just what. - ---- - -## When to Apply - -- **Scenario 1**: Creating any git commit -- **Scenario 2**: Reviewing commit message quality - ---- - -## Quick Reference - -**1. Standard Format**: -``` -Brief summary (50-72 chars) - -## What Changed -- Change 1 -- Change 2 - -## Why -- Rationale - -Co-Authored-By: Claude -``` - ---- - -## Core Principles - -- Imperative mood in summary ("Add" not "Added") -- Why section explains rationale, not just changes -- Model attribution for AI-assisted commits - -## Validation Checklist - -- [ ] Summary 50-72 characters -- [ ] Imperative mood used -- [ ] What Changed section present -- [ ] Why section present -- [ ] Model attribution included -``` - -**Expected Result**: Complete, minimal instruction file with all required components - -### Example 2: Evaluation Criteria for Complex Process - -**Context**: Defining success/failure signals for multi-step process - -**Scenario**: Work logging instruction with observable compliance indicators - -```yaml -evaluation: - success_signals: - - Wiki repository validated before adding entry - - Entry at TOP of date section (reverse chronological) - - Bidirectional links created (wiki <-> GitHub) - - Two-level learning captured (content + process) - - Changes committed and pushed immediately - failure_signals: - - Skipping wiki validation before entry - - Entry appended to bottom (chronological order) - - One-way linking (wiki -> GitHub only) - - Missing sidebar update on first entry of day - - Forgetting to push after commit -``` - -**Expected Result**: Any agent can verify compliance by checking these specific signals - -### Example 3: Quick Reference with Decision Criteria - -**Context**: Instruction that requires judgment, not code patterns - -**Scenario**: When to escalate vs handle autonomously - -```markdown -## Quick Reference - -**Escalation Decision Criteria**: - -| Situation | Action | -|-----------|--------| -| User explicitly requested | Always escalate | -| Destructive operation | Escalate with explanation | -| Uncertainty about intent | Ask clarifying question | -| Within established pattern | Handle autonomously | -| First occurrence of scenario | Document and ask | - -**Key Questions**: -1. Did user explicitly request this action? -2. Is this operation reversible? -3. Does established pattern exist? -4. Am I uncertain about intent? -``` - -**Expected Result**: Decision-heavy instructions provide criteria, not code - ---- - -## Validation Checklist - -Before marking instruction file complete: - -### Structure Validation -- [ ] YAML frontmatter complete with all fields -- [ ] `evaluation` section with success_signals and failure_signals -- [ ] Purpose statement is one sentence -- [ ] Philosophy statement is one sentence -- [ ] "When to Apply" has 3-5 scenarios -- [ ] Quick Reference has 3-5 patterns or decision criteria -- [ ] Core Principles has 3-5 items -- [ ] Step-by-Step has numbered steps with expected outcomes -- [ ] 2-3 complete examples included -- [ ] Validation Checklist uses markdown checkboxes -- [ ] Common Pitfalls documented - -### Quality Validation -- [ ] Success signals are observable and measurable -- [ ] Failure signals are concrete anti-patterns -- [ ] Examples show exact structure (not descriptions) -- [ ] No prose paragraphs in Step-by-Step (use lists) -- [ ] Keywords use snake_case (no spaces or hyphens) -- [ ] Imperative mood throughout ("Create" not "You should create") - -### Routing Validation -- [ ] `applies_to` patterns match intended files -- [ ] Keywords are specific to this instruction -- [ ] NLP description matches When to Apply scenarios - -### Enforcement Validation (Procedural Instructions Only) -- [ ] `enforcement:` block added if instruction has numbered steps or checklists -- [ ] `scope` is `session` (default) or `action` -- [ ] `blocked_tools` categories are appropriate (`mutating`, `reading`, `executing`) -- [ ] `blocked_until` action_type matches requirement (`read_instruction`, `call_mcp_tool`, etc.) -- [ ] If `call_mcp_tool`: `tool_name` field is present and correct -- [ ] If NOT procedural: enforcement block is omitted (not every instruction needs one) - ---- - -## Common Pitfalls - -### Pitfall 1: Missing Evaluation Criteria - -- **Problem**: Instruction has no success/failure signals, making compliance unverifiable -- **Why it happens**: Writing content first, evaluation as afterthought -- **Solution**: Define evaluation section BEFORE writing any other content - -### Pitfall 2: Abstract Examples - -- **Problem**: Examples describe what to do instead of showing exact format -- **Why it happens**: Assuming reader will figure out specifics -- **Solution**: Show complete, copy-pasteable examples with actual content - -### Pitfall 3: Prose Instead of Structure - -- **Problem**: Step-by-step guidance written as paragraphs -- **Why it happens**: Writing for human reading, not agent parsing -- **Solution**: Use numbered steps, bullet lists, and expected outcomes - -### Pitfall 4: Vague Success Signals - -- **Problem**: Success signals like "good quality" or "properly formatted" -- **Why it happens**: Not thinking about how to verify compliance -- **Solution**: Make signals observable ("file exists", "line count > 0", "contains X") - -### Pitfall 5: Keyword Format Errors - -- **Problem**: Keywords use spaces or hyphens, breaking n-gram matching -- **Why it happens**: Not knowing snake_case convention -- **Solution**: Always use snake_case: `issue_closure` not `issue closure` or `issue-closure` - ---- - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| Instruction not triggering | Keywords don't match user input | Add more keyword variants, check snake_case | -| Agent doesn't follow instruction | No clear step-by-step guidance | Add numbered steps with expected outcomes | -| Compliance unclear | Missing evaluation criteria | Add success/failure signals to frontmatter | -| Examples don't help | Examples describe instead of show | Provide complete, copy-pasteable examples | -| Too long to scan | Missing Quick Reference | Add 3-5 most common patterns at top | - ---- - -## Related Instructions - -- **See also**: [agent_compliance_framework.instructions.md](../agentic_workflows/agent_compliance_framework.instructions.md) - How agents should comply with instructions -- **See also**: [_pongogo_collaboration.instructions.md](../_pongogo_core/_pongogo_collaboration.instructions.md) - Communication style preferences - ---- - -**Success Criteria**: Every instruction file has explicit evaluation criteria, clear structure, and concrete examples that enable reliable agent compliance without human judgment. - -**Confidence Check**: Can you verify compliance with this instruction by checking specific signals? Can an agent copy examples directly? Is every step actionable with expected outcome? diff --git a/.pongogo/instructions/github_integration/github_essentials.instructions.md b/.pongogo/instructions/github_integration/github_essentials.instructions.md deleted file mode 100644 index 0dce3842..00000000 --- a/.pongogo/instructions/github_integration/github_essentials.instructions.md +++ /dev/null @@ -1,521 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "GitHub Essentials" -description: "Essential GitHub API patterns, integration standards, and MCP tool usage." -applies_to: - - "**/*" -domains: - - "github" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 1 - triggers: - keywords: - - github_issue - - gh_issue - - create_issue - - issue_lifecycle - - project_board - - completion_tracking - - markdown_checkbox - - delete_issue - - pull_request_workflow - - four_dimensions - - machine-readable - - issue_verification - nlp: "Essential GitHub operations, issue lifecycle, completion tracking with markdown checkboxes, and multi-dimensional verification" -evaluation: - success_signals: - - Issues created with proper workflow and project assignment - - Completion tracking uses markdown checkboxes exclusively - - Multi-dimensional verification before closing (4 dimensions) - - PR vs direct-main decision follows decision matrix - failure_signals: - - Issues created without project assignment - - Emoji used for completion tracking - - Issues closed without verifying all 4 dimensions - - Workflow decision unclear or inconsistent ---- - - -# GitHub Essentials - -**Purpose**: Define essential GitHub operations, issue lifecycle management, and machine-readable tracking formats enabling systematic agent execution. - -**Philosophy**: Machine-readable formats enable agents to parse progress programmatically without manual interpretation. - ---- - -## When to Apply - -Use these standards when: - -- Creating or updating GitHub issues for project tasks -- Managing project boards and issue assignments -- Tracking completion status for features or tasks -- Implementing pull request workflows -- Deleting or closing issues to maintain project hygiene -- Setting up completion tracking for acceptance criteria - ---- - -## Quick Reference - -**Essential GitHub Workflows**: - -**1. Issue Creation (Complete Workflow)**: -```bash -# Step 1: ALWAYS follow task_creation_workflow.instructions.md first -# Step 2: Search existing tasks -gh issue list --label task --state open --search "keyword" - -# Step 3: Create issue with template -gh issue create \ - --title "Task: [Description]" \ - --label "task,domain,priority" \ - --body "[Template content]" - -# Step 4: Assign to project (MANDATORY) -gh project item-add PROJECT_NUMBER \ - --owner OWNER \ - --url "https://github.com/{owner}/{repo}/issues/ISSUE_NUMBER" - -# Step 5: Verify assignment -gh issue view ISSUE_NUMBER --json projectItems -``` - -**2. Project Assignment (Mandatory Every Time)**: -```bash -# All issues MUST be assigned to project -gh project item-add PROJECT_NUMBER \ - --owner {owner} \ - --url "ISSUE_URL" - -# Set initial status -gh project item-edit \ - --project-id PROJECT_ID \ - --id ITEM_ID \ - --field-id STATUS_FIELD_ID \ - --text "Backlog" -``` - -**3. Machine-Readable Completion Tracking**: -```markdown -# CORRECT: Markdown checkboxes (agents can parse) -## Success Indicators -- [ ] Deliverable 1 completed -- [x] Deliverable 2 completed (marked complete) -- [ ] Deliverable 3 completed - -## Acceptance Criteria -- [ ] End-to-end validation complete -- [ ] Quality checks passing - -# WRONG: Emoji (not machine-readable) -Deliverable 1 complete -Deliverable 2 incomplete -``` - -**4. Issue Lifecycle States**: -``` -Backlog → Up Next → In Progress → Ready for Review → Done → Closed - ↓ - On Hold (paused) - ↓ - Blocked (temporary state) -``` - -**5. Pull Request Decision Tree**: -``` -Who is doing the work? -├─ Delegated agent? → Use PR workflow (review required) -├─ External contributor? → Use PR workflow (review + approve) -├─ Human + AI pair? → Direct to main (iterative collaboration) -└─ Documentation only? → Direct to main (low risk) -``` - -**6. Issue Deletion (When Needed)**: -```bash -# Get issue node ID -ISSUE_ID=$(gh api repos/{owner}/{repo}/issues/ISSUE_NUMBER \ - --jq '.node_id') - -# Delete issue via GraphQL -gh api graphql -f query=' -mutation { - deleteIssue(input: {issueId: "'$ISSUE_ID'"}) { - clientMutationId - } -}' -``` - -**7. Status Update Workflow**: -```bash -# Update issue status when work begins -gh issue edit ISSUE_NUMBER --add-label "in-progress" - -# Update status when work complete -gh issue close ISSUE_NUMBER --reason "completed" -``` - -**8. Issue Completion Verification (Before Closing)**: -```markdown -Before closing ANY issue, verify ALL four dimensions: - -✓ Dimension 1 - Deliverables: - - Read each acceptance criterion from issue body - - Verify actual files exist and meet specifications - - Check code AND documentation deliverables - -✓ Dimension 2 - Status Indicators: - - All checkboxes marked [x] - - Project board moved to "Done" - - Work log entry created - -✓ Dimension 3 - Cross-Issue Impacts: - - Update blocked issues when resolving blockers - - Mark dependent checkboxes complete - -✓ Dimension 4 - Knowledge Trail: - - Work log entry for completion - - Learning loop if Task/Epic/Milestone - - Completion comment with evidence - -WARNING: Work log timestamps ≠ proof of completion -TRUST: Direct file verification over indirect signals -``` - ---- - -## Core Principles - -- **Task Workflow First**: Follow task_creation_workflow.instructions.md before creating any GitHub issue -- **Project Assignment Mandatory**: All issues must be assigned to project immediately after creation -- **Machine-Readable Tracking**: Use markdown checkboxes for all completion tracking (never emoji) -- **Lifecycle Clarity**: Close only when complete, delete when obsolete or erroneous -- **Multi-Dimensional Verification**: Before closing, verify deliverables, status sync, cross-issue impacts, and knowledge trail (4 dimensions) -- **Template-Driven**: Use indexed templates for consistent issue structure - -## Step-by-Step Guidance - -### 1. **Issue Creation Workflow** - - **ALWAYS follow task_creation_workflow.instructions.md 6-step process first** - - Search existing tasks for extension opportunities before creating new ones - - Evaluate relationships to existing work (Epic chains, dependencies) - - Apply proper naming conventions: `Epic: [Domain] (v[XX])` or `Task: [Description]` - - Create issues using templates in `.github/ISSUE_TEMPLATE/` directory - - Expected outcome: Issue created with proper structure and relationships - -### 2. **Project Assignment (Mandatory)** - - Assign ALL issues to GitHub project immediately after creation - - Use GitHub CLI: `gh project item-add PROJECT_NUMBER --owner OWNER --url "ISSUE_URL"` - - Set initial status to "Backlog" after project assignment - - Verify assignment completion before proceeding - - Expected outcome: Issue visible in project board - -### 3. **Issue Lifecycle Management** - - Update status when work begins: Backlog → In Progress - - Use project fields for milestone tracking and priority - - Link related issues and pull requests for context - - Close issues only when work is successfully completed - - Delete issues when redundant, erroneous, or made irrelevant - - Expected outcome: Issue state accurately reflects work status - -### 4. **Completion Tracking Standards** - - Use markdown checkboxes for ALL completion tracking: `- [ ]` and `- [x]` - - Apply to: Success Criteria, Acceptance Criteria, Phase tracking, Validation sections - - Update checkbox from `- [ ]` to `- [x]` immediately when work completes - - Note supporting evidence (commit, PR, wiki entry) in issue comment for audit trail - - PROHIBITED: Emoji checkmarks for completion tracking - - Expected outcome: Progress calculable programmatically by agents - -### 5. **Issue Completion Verification (Before Closure)** - - **CRITICAL**: Before closing any issue, verify completion across ALL four dimensions - - **Dimension 1 - Deliverables**: Systematically check each acceptance criterion against actual files - - Read acceptance criteria from issue body - - Verify code deliverables exist and meet specifications (file inspection, not assumption) - - Verify documentation deliverables complete (README updates, guides, specs) - - Run tests if applicable - - **Dimension 2 - Status Indicators**: Synchronize all status locations - - All checkboxes in issue body marked `[x]` - - Project board status matches issue state (move to "Done" when closing) - - Issue state set correctly (closed if complete) - - Work log entry created for issue completion - - **Dimension 3 - Cross-Issue Impacts**: Update dependent issues - - Identify issues this work unblocks - - Update blocked issue bodies with resolution details - - Mark blocked issue checkboxes complete where applicable - - Add section to blocked issues documenting how blocker resolved - - **Dimension 4 - Knowledge Trail**: Document completion - - Work log entry created for Task/Epic/Milestone completion - - Learning loop conducted if applicable - - Completion comment added to issue with evidence links - - Retrospective created if significant learnings - - **Warning**: Work log timestamps, completed code, or conversation history are NOT proof of completion - - **Trust**: Direct verification (file inspection) over indirect signals (timestamps, assumptions) - - Expected outcome: True 100% completion verified before closure, no premature closures - -### 6. **Pull Request Workflow Decision** - - Use PR for: Delegated agent tasks, external contributors, major architectural changes, production deployment - - Use direct main for: Human + AI pair programming, documentation updates, configuration adjustments, iterative development - - Decision criteria: Who is doing work? Review requirement? Work session type? - - Expected outcome: Appropriate workflow chosen based on collaboration model - -### 7. **Issue Deletion (When Needed)** - - Use GitHub GraphQL API `deleteIssue` mutation for proper cleanup - - Command: `gh api graphql -f query='mutation { deleteIssue(input: {issueId: "ISSUE_ID"}) { clientMutationId } }'` - - Get issue node ID from REST API or URL structure - - Document rationale in commit messages or related issues - - Expected outcome: Obsolete issues removed cleanly from project - -## Examples - -### Example 1: Creating a Feature Task with Proper Workflow - -Scenario: Need to add authentication service to application - -```bash -# Step 1: Follow task creation workflow (search, evaluate, plan) -gh issue list --search "authentication" --state all - -# Step 2: Create issue using template -gh issue create \ - --title "Task: Authentication Service Implementation" \ - --body-file .github/ISSUE_TEMPLATE/task.md \ - --label "feature,backend,p1" - -# Step 3: Assign to project (assume project #1) -gh project item-add 1 --owner {owner} --url "https://github.com/{owner}/{repo}/issues/42" - -# Step 4: Set initial status -gh project item-edit --project-id PROJECT_ID --id ITEM_ID --field-id STATUS_FIELD_ID --text "Backlog" -``` - -**Context**: Systematic workflow ensures issue is properly structured, related to existing work, and tracked -**Expected Result**: Issue #42 created, assigned to project, visible in Backlog column - -### Example 2: Machine-Readable Completion Tracking - -Scenario: Task under Epic requiring progress tracking - -```markdown -# [Task]-instruction_file_registry - -**Part of**: [Epic]-knowledge_routing (Issue #45) - -## Success Indicators -- [x] Registry schema designed and documented -- [x] Routing logic implemented -- [ ] Integration tests passing -- [ ] Documentation complete - -## Acceptance Criteria -- [ ] All existing instruction files reviewed -- [ ] Registry schema documented -- [x] registry.json structure created -- [x] Routing logic implemented -- [ ] Integration tests passing with 90%+ coverage -- [ ] Documentation updated in wiki -``` - -**Context**: Agents can parse markdown checkboxes to calculate: 4/9 complete (44%) -**Expected Result**: Programmatic progress tracking without human interpretation - -### Example 3: Pull Request vs Direct Main Decision - -Scenario: Determining workflow for documentation update - -```markdown -# Decision Matrix - -## Scenario A: Agent Delegated Task -- Work type: Cloud agent autonomous execution -- Review: Required for quality gate -- Decision: Pull Request REQUIRED - -## Scenario B: Pair Programming Session -- Work type: Human + AI collaborative development -- Review: Real-time during collaboration -- Decision: Direct Main ALLOWED - -## Scenario C: Production Hotfix -- Work type: Critical bug fix -- Review: Required for production safety -- Decision: Pull Request REQUIRED -``` - -**Context**: Clear decision framework prevents workflow confusion -**Trade-offs**: PRs add review gate but enable delegation; direct main speeds iteration but requires real-time collaboration - -## Validation Checklist - -Before marking GitHub workflow tasks complete: - -- [ ] Issue created following task_creation_workflow.instructions.md -- [ ] Issue assigned to project -- [ ] Initial status set to "Backlog" -- [ ] Completion tracking uses markdown checkboxes (not emoji) -- [ ] Related issues linked in issue body -- [ ] Proper naming convention applied -- [ ] Template used for consistent structure -- [ ] PR workflow decision documented when applicable - -## Common Pitfalls - -### Pitfall 1: Skipping Task Creation Workflow - -- **Problem**: Creating GitHub issue directly without systematic planning -- **Why it happens**: Urgency pressure bypasses established process -- **Solution**: ALWAYS follow task_creation_workflow.instructions.md first -- **Example**: Search for existing authentication tasks before creating new authentication issue - -### Pitfall 2: Using Emoji for Completion Tracking - -- **Problem**: Using emoji instead of markdown checkboxes -- **Why it happens**: Human-readable formats preferred over machine-readable -- **Solution**: Use `- [x]` and `- [ ]` for all completion tracking -- **Example**: Replace "Tests passing" emoji with `- [x] Tests passing` - -### Pitfall 3: Missing Project Assignment - -- **Problem**: Issue created but not assigned to project -- **Why it happens**: Forgotten step after issue creation -- **Solution**: Immediately assign to project using `gh project item-add` -- **Example**: Every issue creation followed by project assignment command - -### Pitfall 4: Closing Instead of Deleting Obsolete Issues - -- **Problem**: Closing issues that are actually redundant or erroneous -- **Why it happens**: Unclear distinction between "completed" and "no longer relevant" -- **Solution**: Close when complete, delete when obsolete/redundant/erroneous -- **Example**: Delete duplicate issue rather than closing it - -## Edge Cases - -### Edge Case 1: Issue Created Before Project Setup - -**When**: Issue exists but project board not yet configured -**Approach**: -- Assign to project retroactively when project board is ready -- Use bulk assignment for multiple legacy issues -- Document assignment gap in issue comment -**Example**: `gh project item-add 1 --owner {owner} --url "https://github.com/{owner}/{repo}/issues/1-20"` - -### Edge Case 2: Partial Completion Requiring Issue Split - -**When**: Issue partially complete but remaining work diverges from original scope -**Approach**: -- Complete and close original issue for work done -- Create new issue for divergent remaining work -- Link issues with "Continuation of #XX" notation -- Update completion tracking to reflect split -**Example**: Close "Authentication Service" after basic auth, create "Advanced Auth Features" for OAuth - -### Edge Case 3: Issue Blocked by External Dependency - -**When**: Issue cannot progress due to external factor (API availability, third-party service) -**Approach**: -- Add "blocked" label to issue -- Document blocking factor in issue comment -- Update project status to "Blocked" column if available -- Set up notification trigger for unblocking condition -**Example**: "Knowledge routing blocked pending instruction file schema finalization" - ---- - -## Batch Operations Automation - -**When**: Performing 5+ repetitive GitHub operations (label creation, issue updates, bulk changes) - -**Pattern**: Create bash scripts for batch operations instead of manual UI clicking or individual CLI commands - -**Why This Works**: -- **Reliability**: Scripts prevent human error in repetitive operations -- **Speed**: Execute 30+ operations in seconds vs minutes of manual work -- **Validation**: Script serves as documentation and can be re-run for verification -- **Debugging**: Easy to inspect and modify if issues occur - -### Approach - -**Step 1: Create Script File** -```bash -cat > /tmp/operation_script.sh << 'EOF' -#!/bin/bash -set -e # Exit on error - -echo "Starting batch operation..." - -# Your operations here -gh label create "label-name" --color "FF0000" --description "Description" -# ... repeat for all items - -echo "Batch operation complete!" -EOF -chmod +x /tmp/operation_script.sh -``` - -**Step 2: Execute** -```bash -/tmp/operation_script.sh -``` - -**Step 3: Validate** -```bash -# Verify results with appropriate gh commands -gh label list -gh issue list --json number,labels -``` - -### When to Use - -**Use Scripts When**: -- 5+ similar operations needed -- Consistency critical (labels, bulk updates) -- Need validation trail -- Operations complex enough to make errors likely - -**Use Manual/Single Commands When**: -- 1-2 operations only -- Interactive decisions needed per item -- Exploratory work (figuring out what to do) - -### Anti-Patterns - -**Don't**: -- Run individual `gh` commands one-by-one in terminal (error-prone for 5+ operations) -- Use UI clicking for bulk operations (slow, no validation trail) -- Create overly complex scripts for simple operations (2-3 commands better run manually) - -### Related - -- **Validation**: Always include validation step in script or as separate script -- **Evidence**: Script files serve as documentation of what was done -- **Reproducibility**: Can re-run if needed or adapt for similar tasks - ---- - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| Issue not appearing in project board | Project assignment missing or failed | Run `gh project item-add` command with correct project ID | -| Completion percentage incorrect | Emoji used instead of markdown checkboxes | Convert all emoji to `- [x]`/`- [ ]` format | -| Cannot delete issue via CLI | GitHub CLI doesn't support deletion | Use GraphQL API: `gh api graphql -f query='mutation { deleteIssue(input: {issueId: "ID"}) }'` | -| PR workflow unclear | Collaboration model ambiguous | Apply decision matrix: delegated → PR, pair programming → direct main | -| Issue templates not rendering | Template syntax error or missing | Validate YAML structure in `.github/ISSUE_TEMPLATE/` | - -## Related Instructions - -- **Prerequisites**: [task_creation_workflow.instructions.md](../project_management/task_creation_workflow.instructions.md) - Complete before creating any GitHub issue -- **See also**: [trust_based_task_execution.instructions.md](../trust_execution/trust_based_task_execution.instructions.md) - Trust-based task execution using markdown checkboxes -- **Next steps**: [github_sub_issues.instructions.md](./github_sub_issues.instructions.md) - Advanced tracking for 10+ execution items -- **See also**: [glossary_maintenance.instructions.md](../project_management/glossary_maintenance.instructions.md) - Keeping glossary current and complete - ---- - -**Success Criteria**: GitHub issues created systematically with proper project assignment, machine-readable completion tracking, and appropriate workflow (PR vs direct main) enabling programmatic progress calculation. - -**Confidence Check**: Can agents parse completion status without human interpretation? Are all issues assigned to project? Does completion tracking use markdown checkboxes exclusively? diff --git a/.pongogo/instructions/github_integration/github_sub_issues.instructions.md b/.pongogo/instructions/github_integration/github_sub_issues.instructions.md deleted file mode 100644 index ae494323..00000000 --- a/.pongogo/instructions/github_integration/github_sub_issues.instructions.md +++ /dev/null @@ -1,475 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "GitHub Sub-Issues Usage Standards" -description: "GitHub sub-issues usage standards, hierarchy patterns, and relationship management." -applies_to: - - "**/*" -domains: - - "github" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 1 - triggers: - keywords: - - sub-issue - - sub_issue - - subissue - - child_issue - - parent_issue - - 10+_items - - progress_tracking - - trackedIssues - - subIssuesSummary - - automatic_progress - - execution_tracking - - embedded_context - nlp: "When and how to use GitHub sub-issues for multi-step execution tracking with automatic progress calculation" -evaluation: - success_signals: - - Sub-issues used only for 10+ execution items - - Items can execute independently (parallel) - - Analysis embedded in sub-issue descriptions - - Automatic progress tracking via GitHub - - Checklists and sub-issues used complementarily - failure_signals: - - Sub-issues for fewer than 10 items (use checkboxes) - - Sub-issues for sequential stages (use checklist) - - Over-granular decomposition (5-minute tasks) - - Missing embedded context (4+ external sources needed) - - Using sub-issues when checkboxes sufficient ---- - - -# GitHub Sub-Issues Usage Standards - -**Purpose**: Define when and how to use GitHub sub-issues for multi-step execution tracking with automatic progress calculation and programmatic navigation. - -**Philosophy**: Use sub-issues when programmatic progress queries, automatic percentage calculation, and zero-maintenance synchronization provide clear value over manual tracking. - ---- - -## When to Apply - -Use sub-issues when: - -- Epic task involves 10+ discrete execution items requiring systematic tracking -- Items can execute independently (parallel-executable, order-flexible) -- Programmatic progress queries provide value for agent decision-making -- Multiple context sources currently required (reducing to 1-2 sources) -- Long-running implementation spans multiple sessions/weeks - -Do NOT use sub-issues when: - -- Fewer than 10 execution items (use markdown checkboxes instead) -- Items are tightly coupled sequential steps (use checklist in Issue description) -- Items don't map to trackable GitHub issues -- Over-granular decomposition (5-minute tasks) - ---- - -## Quick Reference - -**Sub-Issues Decision Criteria**: - -**1. Use Sub-Issues When** (All must be true): -- [ ] **10+ discrete execution items** (threshold justified) -- [ ] **Items executable independently** (parallel or order-flexible) -- [ ] **Programmatic progress queries valuable** (agents need automatic tracking) -- [ ] **Context currently spread across 4+ sources** (reducing to 1-2) -- [ ] **Long-running work** (multiple sessions/weeks) - -**2. Do NOT Use Sub-Issues When** (Any is true): -- [ ] **< 10 execution items** → Use markdown checkboxes instead -- [ ] **Tightly coupled sequential steps** → Use checklist in Issue description -- [ ] **Items don't map to GitHub issues** → Not suitable for issue tracking -- [ ] **Over-granular tasks** (5-minute edits) → Combine into meaningful units - -**3. Sub-Issues vs Checklists** (Complementary, Not Competing): -``` -Checklists (within Issue): -├─ INTERNAL TRACKING -├─ Sequential or simple steps -├─ Manual checkbox updates -└─ Within single Issue scope - -Sub-Issues: -├─ EXTERNAL EXECUTION -├─ Parallel items (can execute independently) -├─ Automatic progress tracking -└─ Across multiple execution units (GitHub Issues) -``` - -**4. Sub-Issue Creation Pattern**: -```bash -# Step 1: Create parent issue -gh issue create \ - --title "[Epic Task Title] - Sub-Issues Tracking" \ - --label "task,tracking" \ - --body "Overview and execution approach" - -# Step 2: Create sub-issues with embedded context -for i in {1..15}; do - gh issue create \ - --title "Sub-Issue: [Action] [Target]" \ - --label "sub-issue" \ - --body "Embedded analysis and acceptance criteria" \ - --assignee @me - - # Link to parent (GitHub UI or GraphQL) -done -``` - -**5. Progress Query Pattern (GraphQL)**: -```graphql -query GetSubIssuesProgress($owner: String!, $repo: String!, $number: Int!) { - repository(owner: $owner, name: $repo) { - issue(number: $number) { - title - trackedIssues(first: 100) { - totalCount - nodes { - number - title - state - closed - } - } - } - } -} - -# Automatic calculation: -# Progress = (closedCount / totalCount) * 100% -``` - -**6. Sub-Issue Naming Convention**: -```markdown -# Simple and direct -Sub-Issue: Add Quick Reference to observability_patterns.instructions.md -Sub-Issue: Update validation framework with new standards -Sub-Issue: Implement rate limiting middleware -Sub-Issue: Document API endpoints in OpenAPI spec -``` - -**7. When to Use Markdown Checkboxes Instead**: -```markdown -# < 10 items, sequential, within single task -## Implementation Checklist - -### Acceptance Criteria -- [ ] Authentication middleware implemented -- [ ] Token validation logic added -- [ ] Error handling for invalid tokens -- [ ] Integration tests added - -# 4 items = Use checkboxes, NOT sub-issues -``` - ---- - -## Core Principles - -- **Checklists vs Sub-Issues are Complementary**: Checklists track INTERNAL steps (sequential items within Issue), sub-issues track EXTERNAL execution (parallel work across GitHub Issues) -- **10+ Item Threshold**: Sub-issues justified only when tracking 10+ discrete execution units -- **Automatic Progress**: GitHub calculates completion percentage, no manual tracking needed -- **Programmatic Navigation**: Single GraphQL query retrieves complete hierarchy (child → parent → Epic) -- **Context Reduction**: Embed analysis in sub-issue descriptions (4+ sources → 1-2 sources) - -## Step-by-Step Guidance - -### 1. **Verify Sub-Issues Suitability** - - Confirm 10+ execution items exist - - Verify items represent meaningful work (not trivial edits) - - Check items can execute independently - - Validate programmatic progress tracking provides value - - Ensure items map to GitHub issues - - Expected outcome: Sub-issues approach justified with clear criteria - -### 2. **Plan Sub-Issue Organization** - - One sub-issue per discrete execution item - - Embed relevant analysis/recommendations in sub-issue description - - Define clear acceptance criteria for each sub-issue - - Document dependencies if execution order requirements exist - - Expected outcome: Sub-issue structure planned systematically - -### 3. **Create Parent Issue Structure** - - Title: `[Epic Task Title] - Sub-Issues Tracking` - - Add overview describing overall objective - - Document execution approach (how sub-issues will be processed) - - Include progress tracking section (GitHub auto-calculates) - - Add success criteria for overall completion - - Expected outcome: Parent issue ready to coordinate sub-issues - -### 4. **Create Sub-Issues with Embedded Context** - - Use GitHub UI or API to create sub-issues linked to parent - - Embed analysis recommendations directly in sub-issue descriptions - - Include links to source issues/files being modified - - Add acceptance criteria specific to that sub-issue - - Simple naming: `Sub-Issue: [Action] [Target] ([Optional Context])` - - Expected outcome: Sub-issues created with complete execution context - -### 5. **Validate Structure** - - Verify parent issue shows automatic progress: "X/Y completed (Z%)" - - Confirm sub-issues render with checkboxes in parent issue body - - Test GraphQL queries for programmatic progress access - - Validate agents can discover and execute sub-issues systematically - - Expected outcome: Sub-issue tracking operational and accessible - -### 6. **Execute Sub-Issue Workflow** - - Query open sub-issues using GraphQL API - - Read sub-issue description for embedded analysis/context - - Execute work per recommendations - - Close sub-issue upon completion with evidence comment - - Parent progress automatically updates - - Expected outcome: Systematic execution with automatic tracking - -## Examples - -### Example 1: Checklists AND Sub-Issues Together (Common Pattern) - -Scenario: Project needs to update 25 existing task issues with improved templates - -```markdown -# [Task]-comprehensive_task_updates - -**Part of**: [Epic]-template_improvements (Issue #55) - -## Coordination Checklist (Internal tracking): - -### Setup & Planning -- [ ] Analyze existing task issues for update patterns -- [ ] Design sub-issue template with embedded recommendations -- [ ] Foundation ready for execution - -### Execution Tracking -- [ ] All 25 sub-issues created -- [ ] Sub-issues being executed (GitHub shows: 12/25 completed) -- [ ] Execution proceeding systematically - -### Completion Validation -- [ ] All sub-issues closed (GitHub shows: 25/25 completed) -- [ ] Quality validated across all updated tasks -- [ ] Task operationally complete - -## Sub-Issues (External Execution - Parallel): -[GitHub renders automatically with progress: 12/25 completed (48%)] - -- Sub-Issue: Update Task (Authentication Service) -- Sub-Issue: Update Task (Routing Service) -- Sub-Issue: Update Task (Audit Service) -- ... (22 more) -``` - -**Context**: Parent task has checklist for coordination while sub-issues track discrete update targets -**Expected Result**: Execution checklist completion depends on sub-issue progress, measured automatically by GitHub - -### Example 2: API Navigation Pattern (Child → Parent → Epic) - -Scenario: Agent executing Sub-Issue #47, needs parent Epic context - -```bash -# Single GraphQL query retrieves complete hierarchy -gh api graphql \ - -f owner="{owner}" \ - -f repo="{repo}" \ - -F issueNumber=47 \ - -f query=' - query GetHierarchy($owner: String!, $repo: String!, $issueNumber: Int!) { - repository(owner: $owner, name: $repo) { - issue(number: $issueNumber) { - number - title - body - # Navigate UP to parent - parent { - number - title # Contains Epic info - # Navigate DOWN to siblings - subIssues(first: 100) { - totalCount - nodes { - number - title - state - } - } - subIssuesSummary { - total - completed - percentCompleted - } - } - } - } - }' - -# Result shows: -# - Sub-Issue #47 details -# - Parent: Issue #38 "[Task]-registry_implementation" (Part of: [Epic]-knowledge_routing) -# - Epic: [Epic]-knowledge_routing -# - Siblings: 18 other sub-issues -# - Progress: 7/19 completed (37%) -``` - -**Context**: Single API call provides complete context for agent decision-making -**Expected Result**: Agent understands Epic context, parent task, sibling progress without multiple queries - -### Example 3: Sub-Issue with Embedded Analysis - -Scenario: Creating sub-issue that embeds analysis to reduce context sources - -```markdown -# Sub-Issue: Retrofit Authentication Task - -**Parent**: [Task]-comprehensive_retrofit (Part of: [Epic]-task_structure) - -## Source Task -[Task: Authentication Service Implementation](https://github.com/{owner}/{repo}/issues/XX) - -## Analysis Summary -**Update Category**: HIGH - Complex task requiring comprehensive checklist structure - -**Recommended Structure**: -- Apply phased checklist approach (Setup → Implementation → Validation) -- Success Criteria: 6 items across 3 sections -- Acceptance Criteria: 4 items validating deliverables -- Completion Validation: 2 items ensuring operational readiness - -**Content Preservation Requirements**: -- Maintain Epic relationship: [Epic]-task_structure -- Preserve authentication technical context -- Keep JWT implementation details -- Retain OAuth integration specifications - -## Execution Steps -1. Read task issue current body -2. Trust embedded recommendations without re-analysis -3. Implement retrofit per structure above -4. Validate transformation meets acceptance criteria -5. Close this sub-issue with commit reference - -## Acceptance Criteria -- [ ] Task body updated with phased checklist structure -- [ ] All technical context preserved -- [ ] Epic relationship documented -- [ ] Transformation validated via GitHub API - -## Related -- Parent: [Task]-comprehensive_retrofit (Issue #55) -- Epic: [Epic]-task_structure -- Category: Service Implementation Tasks -``` - -**Context**: Sub-issue contains all context needed - agent reads once, executes directly -**Trade-offs**: Longer sub-issue description, but eliminates need for external analysis files - -## Validation Checklist - -Before creating sub-issues structure: - -### Justification Validation -- [ ] Item count ≥ 10 discrete execution units -- [ ] Items represent meaningful work (not trivial edits) -- [ ] Items can execute independently (order-flexible) -- [ ] Programmatic progress tracking provides value -- [ ] Items map to GitHub issues (not abstract concepts) - -### Anti-Pattern Avoidance -- [ ] NOT using sub-issues for sequential phases -- [ ] NOT creating sub-issues for individual file edits -- [ ] NOT decomposing into trivial 5-minute tasks -- [ ] NOT using sub-issues when checkboxes sufficient - -### Implementation Readiness -- [ ] Parent issue description explains execution approach -- [ ] Sub-issue template designed with embedded analysis -- [ ] GraphQL queries prepared for programmatic access -- [ ] Agent execution workflow documented - -## Common Pitfalls - -### Pitfall 1: Using Sub-Issues for Sequential Stages - -- **Problem**: Creating sub-issues for "Design", "Implementation", "Testing" stages -- **Why it happens**: Confusion between sequential stages and parallel items -- **Solution**: Use checklist in Issue description for sequential stages -- **Example**: Feature development has Design → Implement → Validate checklist sections, not 3 sub-issues - -### Pitfall 2: Creating Sub-Issues Below 10-Item Threshold - -- **Problem**: Using sub-issues for 5 execution items -- **Why it happens**: Overengineering simple tracking needs -- **Solution**: Use markdown checkboxes for <10 items -- **Example**: Task with 7 acceptance criteria uses checkboxes, not sub-issues - -### Pitfall 3: Over-Granular Decomposition - -- **Problem**: Sub-issue for every individual file edit (30 sub-issues for 30 files) -- **Why it happens**: Misunderstanding "discrete execution unit" concept -- **Solution**: Group related files into meaningful execution units -- **Example**: "Update authentication middleware" (5 files) as one sub-issue, not 5 separate sub-issues - -### Pitfall 4: Missing Embedded Analysis - -- **Problem**: Sub-issues require agent to consult 4 external sources -- **Why it happens**: Failing to embed recommendations in sub-issue descriptions -- **Solution**: Copy key analysis into sub-issue description -- **Example**: Include retrofit recommendations directly in sub-issue, not just link to external doc - -## Edge Cases - -### Edge Case 1: Sub-Issue Has Own Phases - -**When**: Individual sub-issue represents complex work needing phased execution -**Approach**: -- Sub-issue can have its own checklist sections internally -- Parent checklist tracks overall task progression -- Sub-issue checklist tracks individual item execution -- Both use markdown checkboxes for tracking -**Example**: Sub-issue "Update Authentication Task" has Analysis → Implementation → Validation checklist sections - -### Edge Case 2: Parent Progress Blocked by Sub-Issue Dependency - -**When**: Some sub-issues must complete before others can start -**Approach**: -- Document dependencies explicitly in sub-issue descriptions -- Use "blocked" label on dependent sub-issues -- Agent queries for unblocked sub-issues only -- Parent phase gates track dependency milestones -**Example**: Sub-issues 1-5 (foundation) must complete before sub-issues 6-20 (implementation) can start - -### Edge Case 3: Sub-Issue Reveals Additional Work - -**When**: Executing sub-issue uncovers need for more sub-issues -**Approach**: -- Create additional sub-issues as discovered -- Update parent issue's execution tracking count -- Document scope discovery in work log -- Adjust completion expectations transparently -**Example**: Updating 25 tasks reveals 3 more needing updates → add 3 sub-issues (25 → 28 total) - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| `parent` field returns `null` | Issue not linked as sub-issue | Use `addSubIssue` GraphQL mutation to establish relationship | -| `subIssues` returns empty | No sub-issues created yet | Verify sub-issues exist and are properly linked | -| Epic parsing fails | Parent title doesn't match current format | Ensure parent follows "[Task]-name" format with "Part of: [Epic]-name" when applicable | -| Progress not auto-updating | Sub-issue state not changing | Close sub-issues properly, don't just mark complete | -| Sub-issue context insufficient | Analysis not embedded | Add key recommendations directly to sub-issue description | - -## Related Instructions - -- **Prerequisites**: [task_creation_workflow.instructions.md](../project_management/task_creation_workflow.instructions.md) - Follow before creating parent issue -- **See also**: [trust_based_task_execution.instructions.md](../trust_execution/trust_based_task_execution.instructions.md) - Phases complement sub-issues, not replace them -- **Integration**: [github_essentials.instructions.md](./github_essentials.instructions.md) - Machine-readable tracking applies to both checkboxes and sub-issues -- **See also**: [glossary_maintenance.instructions.md](../project_management/glossary_maintenance.instructions.md) - Keeping glossary current and complete - ---- - -**Success Criteria**: Sub-issues used only when 10+ items justify overhead, with automatic progress tracking, embedded context reducing sources to 1-2, and bidirectional API navigation enabling systematic agent execution. - -**Confidence Check**: Do you have 10+ discrete execution items? Can items execute independently? Will programmatic progress queries add value? Is analysis embedded in sub-issue descriptions? diff --git a/.pongogo/instructions/project_management/glossary_maintenance.instructions.md b/.pongogo/instructions/project_management/glossary_maintenance.instructions.md deleted file mode 100644 index 2f9d833a..00000000 --- a/.pongogo/instructions/project_management/glossary_maintenance.instructions.md +++ /dev/null @@ -1,602 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Glossary Maintenance" -description: "Maintain project glossary with consistent terminology across documentation." -applies_to: - - "**/*" -domains: - - "project_management" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 1 - triggers: - keywords: - - glossary - - terminology - - project_glossary - - PM_ontology - - term_definition - - glossary_maintenance - - taxonomy - - knowledge_graph - nlp: "Systematic maintenance of Project Glossary as authoritative source for PM terminology and knowledge graph taxonomy" -evaluation: - success_signals: - - Term includes Definition, Category, Relationships, Usage, Example - - Term added to both category section AND alphabetical index - - Bidirectional cross-references created (See also) - - Wiki submodule reference updated in main repo - - New PM terms added immediately when introduced - failure_signals: - - Term missing required sections (Definition, Category) - - One-location entry (category OR index, not both) - - Missing cross-references to related terms - - Forgot wiki submodule update in main repo - - Vague or circular definitions ---- - - -# Project Glossary Maintenance - -**Purpose**: Establish systematic glossary maintenance ensuring Project Glossary remains authoritative, current, and complete as the foundational PM ontology for the knowledge graph. - -**Philosophy**: The Project Glossary is a living taxonomy - comprehensive, precise entries enable agents to understand PM concepts consistently and make informed decisions without ambiguity. Glossary is the single source of truth for terminology, relationships, and taxonomy structure. - ---- - -## When to Apply - -This instruction applies when: - -- **Scenario 1**: Introducing new PM concepts, processes, or terminology (new term requires glossary entry) -- **Scenario 2**: Clarifying existing terminology or resolving ambiguity (term definition needs refinement) -- **Scenario 3**: Discovering missing relationships or cross-references (term connections need documentation) -- **Scenario 4**: Completing Milestones, Epics, or significant Tasks (learning loop may surface new terms) -- **Scenario 5**: Creating or updating instruction files with domain-specific terminology (ensure terms defined) - ---- - -## Quick Reference - -**Most Common Patterns**: - -**1. Add New Term to Glossary**: -```markdown -### Term Name - -**Definition**: Clear, concise definition (1-2 sentences). - -**Category**: Taxonomy bucket (PM Hierarchy, GitHub Objects, etc.) - -**Relationships**: -- **Parent**: Parent concept (or "None" if top-level) -- **Children**: Child concepts (or "None" if leaf node) -- **Related**: Related terms in other categories - -**Usage**: When/where this term is used in practice. - -**Example**: -``` -Concrete example demonstrating the term -``` - -**See also**: [[#related-term-1]], [[#related-term-2]] -``` - -**2. Update Existing Term**: -```bash -# Check current definition -grep -A 20 "^### Term Name" wiki/Project-Glossary.md - -# Update with Edit tool maintaining structure -# Preserve Definition, Category, Relationships, Usage, Example, See also -``` - -**3. Validate Cross-References**: -```bash -# Check all "See also" links resolve -grep -o '\[\[#[a-z-]*\]\]' wiki/Project-Glossary.md | sort -u > refs.txt -grep "^### " wiki/Project-Glossary.md | sed 's/### //' > terms.txt -# Compare refs.txt to terms.txt to find broken links -``` - -**4. Commit Glossary Changes**: -```bash -cd {project_root}/wiki -git add Project-Glossary.md -git commit -m "Update Project Glossary: [description of changes]" -git push - -cd {project_root} -git add wiki -git commit -m "Update wiki submodule: Glossary changes" -git push -``` - ---- - -## Core Principles - -- **Single Source of Truth**: `wiki/Project-Glossary.md` is authoritative source for ALL project terminology -- **PM Ontology Foundation**: Glossary defines taxonomy structure for knowledge graph and agent reasoning -- **Structured Entries**: Every term includes Definition, Category, Relationships, Usage, Example, See also -- **Bidirectional Relationships**: Parent-child and related-term connections documented explicitly -- **Consistency Over Time**: Terms maintain consistent meaning; definition changes require decision archaeology -- **Immediate Update**: New terms added when introduced; don't accumulate glossary debt -- **Learning Loop Integration**: Learning loops and retrospectives surface new terms requiring documentation - -## Step-by-Step Guidance - -### Adding New Term - -1. **Identify Terminology Trigger** - - Introducing new PM concept in instruction files, docs, or wiki - - Learning loop surfaces undefined term causing ambiguity - - User introduces term needing formal definition - - Expected outcome: Term identified as needing glossary entry - - Rationale: Prevents terminology drift and agent confusion - -2. **Validate Term Doesn't Exist** - - Search glossary for term: `grep -i "### term" wiki/Project-Glossary.md` - - Check for synonyms or related terms in same category - - Verify term isn't covered under different name - - Success indicator: Term confirmed as net-new addition - - Rationale: Prevents duplicate entries with different names - -3. **Determine Category and Relationships** - - Assign to appropriate category: PM Hierarchy, GitHub Objects, Process Concepts, Agent Roles, Quality Concepts, Knowledge Architecture, Phases & Checklists - - Identify parent concept (or "None" if top-level) - - Identify child concepts (or "None" if leaf node) - - List related terms in other categories - - Expected outcome: Term positioned correctly in taxonomy - - Rationale: Maintains ontology structure for knowledge graph - -4. **Draft Complete Entry** - - Write 1-2 sentence definition (clear, precise, unambiguous) - - Document usage context (where/when term applies) - - Create concrete example demonstrating term - - List "See also" cross-references - - Common variation: Terms with GitHub mappings include mapping details - - Integration point: Examples reference real files/artifacts when possible - -5. **Insert in Glossary (Two Locations)** - - Add to category section (maintains category grouping) - - Add to alphabetical index (enables quick lookup) - - Maintain consistent formatting and structure - - Success indicator: Term appears in both locations with full structure - - Rationale: Dual-access pattern (browse by category OR lookup alphabetically) - -6. **Update Cross-References** - - Add "See also" link in new entry pointing to related terms - - Update related terms' "See also" sections pointing back to new term - - Verify all cross-reference links resolve (use anchor format: `[[#term-name]]`) - - Expected outcome: Bidirectional navigation between related concepts - - Rationale: Glossary as traversable knowledge graph, not flat list - -7. **Commit and Push to Wiki** - - Commit to wiki repository with descriptive message - - Push to remote wiki - - Update wiki submodule reference in main repo - - Commit and push main repo submodule update - - Success indicator: Changes visible in both wiki and main repo - - Rationale: Maintains synchronized state across repositories - -### Updating Existing Term - -1. **Identify Update Trigger** - - Term definition ambiguous or incomplete - - Usage context changed - - Relationships discovered or evolved - - User feedback indicates confusion - - Expected outcome: Clear rationale for update documented - -2. **Document Change Rationale** - - If definition changes significantly, create Decision Archive entry - - Document why change needed (ambiguity, evolution, correction) - - Preserve historical context if definition evolved over time - - Success indicator: Change traceable and justified - -3. **Update Term Entry** - - Modify definition, usage, example, or relationships as needed - - Maintain structure (don't remove required sections) - - Update version metadata if glossary has version number - - Expected outcome: Term entry accurate and complete - -4. **Validate Cross-References Still Resolve** - - Check all "See also" links in updated entry - - Check other entries linking TO updated term - - Update cross-references if term name changed - - Success indicator: No broken links after update - -5. **Commit with Context-Rich Message** - - Explain what changed and why in commit message - - Reference issue/PR/decision if applicable - - Follow commit message format - - Success indicator: Future agents understand why change was made - -### Maintenance Triggers - -**Automatic triggers** (glossary update REQUIRED): -- New PM concept introduced in any instruction file -- New process concept documented in docs/processes/ -- New quality concept added to validation frameworks -- New agent role defined in Multi-Agent-Architecture.md -- Learning loop surfaces terminology ambiguity -- Milestone/Epic/Task completion retrospective identifies new terms - -**On-demand triggers** (glossary review recommended): -- Quarterly glossary audit (completeness check) -- After major PM methodology changes -- When agents express confusion about term meaning -- After introducing new knowledge architecture patterns - ---- - -## Examples - -### Example 1: Adding New Term (Complete Workflow) - -**Context**: Learning loop surfaces new term "Design Artifact" that needs formal definition. - -```bash -#!/bin/bash -# Complete workflow for adding new glossary term - -# Step 1: Validate term doesn't exist -cd {project_root} -grep -i "### Design Artifact" wiki/Project-Glossary.md -# (returns nothing - term is new) - -# Step 2: Use Edit tool to add term to category section -# Add to "Process Concepts" section in wiki/Project-Glossary.md -``` - -```markdown -### Design Artifact - -**Definition**: Structured document capturing technical design decisions, architecture diagrams, API contracts, or data models before implementation begins. Core component of design-first development. - -**Category**: Process Concepts - -**Relationships**: -- **Parent**: Design-First Development -- **Children**: Architecture Diagram, API Contract, Data Model, Technical Spec -- **Related**: [[#mmf-minimum-marketable-feature]], [[#task]], [[#validation]] - -**Usage**: Created during Task planning phase before implementation. Referenced throughout development and validation. Required for Tasks introducing new architecture, APIs, or data models. - -**Example**: -``` -Task: [Task]-implement_user_authentication - -Design Artifacts: -- docs/design/authentication-architecture.md (system design) -- docs/design/auth-api-contract.yaml (API specification) -- docs/design/user-session-data-model.md (database schema) - -Implementation follows design artifacts, validation verifies implementation matches design. -``` - -**See also**: [[#design-first-development]], [[#task]], [[#validation-gate]] -``` - -```bash -# Step 3: Add to alphabetical index -# Insert in alphabetical position maintaining format - -# Step 4: Update cross-references -# Add link TO new term in related entries: -# - Design-First Development → See also: [[#design-artifact]] -# - Task → See also: [[#design-artifact]] -# - Validation Gate → See also: [[#design-artifact]] - -# Step 5: Commit and push -cd wiki -git add Project-Glossary.md -git commit -m "Add glossary term: Design Artifact - -Added formal definition for Design Artifact term surfaced during learning loop. -Positioned in Process Concepts category with bidirectional links to related terms." -git push - -cd {project_root} -git add wiki -git commit -m "Update wiki submodule: Design Artifact term added" -git push -``` - -**Expected Result**: Design Artifact term defined in glossary, accessible via category browsing and alphabetical index, cross-referenced with related terms, changes committed to both wiki and main repo. - -### Example 2: Updating Term Definition (Clarification) - -**Context**: User feedback indicates "Sub-Task" definition ambiguous regarding GitHub Sub-Issue relationship. - -```bash -# Step 1: Document update rationale -# User clarified: "Sub-Tasks are PM concept; Sub-Issues are GitHub objects" -# Need to update glossary to reflect this distinction - -# Step 2: Read current definition -cd {project_root} -``` - -```markdown -# Current definition (ambiguous): -### Sub-Task - -**Definition**: Smallest execution detail beneath a Task, may be tracked as GitHub Sub-Issue. -... -``` - -```markdown -# Updated definition (clarified): -### Sub-Task - -**Definition**: Smallest execution detail beneath a Task in PM hierarchy. PM concept (not GitHub object). May be tracked as GitHub Sub-Issue when significant enough to warrant platform tracking (10+ items, multi-session execution, programmatic queries, or multi-agent coordination). - -**Category**: PM Hierarchy (Level 4) - -**Relationships**: -- **Parent**: [[#task]] -- **Children**: None (leaf node) -- **GitHub Mapping**: May become Sub-Issue (GitHub object) if tracking warranted -- **Related**: [[#sub-issue]], [[#github-issue]] - -**Usage**: Used to decompose Task into execution steps. Not all Sub-Tasks need GitHub tracking. Only create Sub-Issues for significant Sub-Tasks. - -**Example**: -``` -Task: [Task]-implement_authentication (GitHub Issue #45) - Sub-Tasks (PM concept): - - Design authentication flow (internal planning - no Sub-Issue) - - Implement login endpoint (significant - tracked as Sub-Issue) - - Implement logout endpoint (significant - tracked as Sub-Issue) - - Write unit tests (significant - tracked as Sub-Issue) - - Update API docs (internal - no Sub-Issue) - -Result: 5 Sub-Tasks, 3 tracked as Sub-Issues -``` - -**See also**: [[#task]], [[#sub-issue]], [[#github-issue]], [[#mmf-minimum-marketable-feature]] -``` - -```bash -# Step 3: Use Edit tool to update definition - -# Step 4: Validate cross-references -grep -o '\[\[#[a-z-]*\]\]' wiki/Project-Glossary.md | grep -i "sub-task\|sub-issue" -# Verify all links resolve - -# Step 5: Commit with context -cd wiki -git add Project-Glossary.md -git commit -m "Clarify Sub-Task vs Sub-Issue distinction in glossary - -Updated Sub-Task definition to clarify PM concept vs GitHub object distinction. -Added criteria for when Sub-Tasks warrant Sub-Issue tracking (significance threshold). -Expanded example showing 5 Sub-Tasks with only 3 tracked as Sub-Issues. - -Context: User feedback highlighted ambiguity in Sub-Task/Sub-Issue usage." -git push - -cd {project_root} -git add wiki -git commit -m "Update wiki submodule: Sub-Task definition clarified" -git push -``` - -**Expected Result**: Sub-Task definition clarified with explicit distinction from Sub-Issue, significance threshold documented, example expanded, changes committed with full context. - -### Example 3: Quarterly Glossary Audit - -**Context**: Quarterly maintenance to ensure completeness and consistency. - -```bash -#!/bin/bash -# Quarterly glossary audit workflow - -cd {project_root} - -# Check 1: Verify all instruction files reference defined terms -echo "=== Checking instruction files for undefined terms ===" -# Extract terms from instruction files -grep -h "^\*\*" knowledge/instructions/**/*.instructions.md | \ - sed 's/\*\*//g' | sed 's/:.*$//' | sort -u > instruction_terms.txt - -# Extract terms from glossary -grep "^### " wiki/Project-Glossary.md | sed 's/### //' | sort -u > glossary_terms.txt - -# Find terms in instructions not in glossary -comm -23 instruction_terms.txt glossary_terms.txt > missing_terms.txt - -echo "Found $(wc -l < missing_terms.txt) potentially undefined terms" - -# Check 2: Verify cross-references resolve -echo "=== Validating cross-references ===" -grep -o '\[\[#[a-z-]*\]\]' wiki/Project-Glossary.md | \ - sed 's/\[\[#//' | sed 's/\]\]//' | sort -u > referenced_terms.txt - -# Check if all referenced terms exist -while read ref; do - if ! grep -q "^### $(echo $ref | sed 's/-/ /g')" wiki/Project-Glossary.md; then - echo "Broken reference: [[#$ref]]" - fi -done < referenced_terms.txt - -# Check 3: Validate structure consistency -echo "=== Validating entry structure ===" -# Each term should have: Definition, Category, Relationships, Usage, Example, See also -grep "^### " wiki/Project-Glossary.md | while read term; do - term_name=$(echo $term | sed 's/### //') - - # Check required sections exist after term - if ! grep -A 30 "^### $term_name" wiki/Project-Glossary.md | grep -q "^\*\*Definition\*\*:"; then - echo "Missing Definition: $term_name" - fi - if ! grep -A 30 "^### $term_name" wiki/Project-Glossary.md | grep -q "^\*\*Category\*\*:"; then - echo "Missing Category: $term_name" - fi - # ... (similar checks for other required sections) -done - -# Check 4: Generate audit report -echo "=== Audit Summary ===" > glossary_audit.txt -echo "Date: $(date)" >> glossary_audit.txt -echo "Total terms: $(grep -c '^### ' wiki/Project-Glossary.md)" >> glossary_audit.txt -echo "Missing terms: $(wc -l < missing_terms.txt)" >> glossary_audit.txt -echo "Broken references: $(grep -c 'Broken reference' glossary_audit.txt || echo 0)" >> glossary_audit.txt - -cat glossary_audit.txt -``` - -**Expected Result**: Audit identifies missing terms, broken cross-references, and structural inconsistencies. Follow-up tasks created to address gaps. - ---- - -## Validation Checklist - -- [ ] Glossary repository validated (exists, up-to-date, accessible) -- [ ] Term validated as net-new (no duplicates or synonyms) -- [ ] Category assigned correctly (PM Hierarchy, GitHub Objects, Process Concepts, etc.) -- [ ] Definition clear and concise (1-2 sentences, unambiguous) -- [ ] Relationships documented (parent, children, related terms) -- [ ] Usage context provided (where/when term applies) -- [ ] Concrete example included (demonstrates term in practice) -- [ ] Cross-references added ("See also" links to related terms) -- [ ] Term added to category section (grouped with similar terms) -- [ ] Term added to alphabetical index (enables quick lookup) -- [ ] Related terms updated with bidirectional links (if applicable) -- [ ] All cross-reference links validated (resolve to existing terms) -- [ ] Changes committed with context-rich message (why change made) -- [ ] Wiki repository pushed to remote (changes visible) -- [ ] Main repo submodule reference updated (wiki submodule pointer current) -- [ ] Main repo pushed to remote (submodule update visible) - ---- - -## Common Pitfalls - -### Pitfall 1: Adding Term Without Category - -- **Problem**: New term added with definition but no category assignment -- **Why it happens**: Focus on definition without considering taxonomy structure -- **Solution**: ALWAYS assign category; glossary is ontology foundation for knowledge graph -- **Example**: "Validation Gate" added without category - agents can't position term in taxonomy structure - -### Pitfall 2: One-Location Entry (Category OR Index, Not Both) - -- **Problem**: Term added to category section but not alphabetical index (or vice versa) -- **Why it happens**: Forgetting dual-access pattern (browse by category, lookup alphabetically) -- **Solution**: ALWAYS add to both locations; verify term appears in category section AND index -- **Example**: "Design Artifact" in Process Concepts section but not in alphabetical index - users searching alphabetically can't find term - -### Pitfall 3: Missing Cross-References - -- **Problem**: New term related to existing terms but "See also" links not created -- **Why it happens**: Focus on term definition without considering relationship web -- **Solution**: ALWAYS identify related terms; add bidirectional "See also" links -- **Example**: "Sub-Task" added but doesn't link to "Task" or "Sub-Issue" - agents can't navigate relationship structure - -### Pitfall 4: Vague or Circular Definitions - -- **Problem**: Definition uses term being defined or references undefined concepts -- **Why it happens**: Assuming reader understands context or related terminology -- **Solution**: Define term clearly without circular reference; link to related concepts -- **Example**: "Epic is a grouping of Tasks" without defining what Task means - reader needs to know Task first - -### Pitfall 5: Forgetting Submodule Update - -- **Problem**: Wiki changes committed and pushed but main repo submodule reference not updated -- **Why it happens**: Wiki is separate repository; easy to forget main repo tracks submodule pointer -- **Solution**: ALWAYS update main repo after wiki changes; two-step commit process -- **Example**: Glossary updated in wiki but main repo still points to old wiki commit - agents accessing via main repo see stale glossary - ---- - -## Edge Cases - -### Edge Case 1: Term Name Conflicts with Existing Term - -**When**: Attempting to add new term but name conflicts with existing term in different category - -**Approach**: -1. Check if terms are actually synonyms (same concept, different names) -2. If synonyms, update existing term with alternate names section -3. If distinct concepts, use qualified name (e.g., "Validation (Quality)" vs "Validation (GitHub)") -4. Document distinction clearly in definitions - -**Example**: "Milestone" as PM concept vs "Milestone (GitHub)" as platform object - qualified names disambiguate. - -### Edge Case 2: Term Relationship Evolves (Parent Changes) - -**When**: Term's parent concept changes due to taxonomy restructuring - -**Approach**: -1. Document restructuring rationale in Decision Archive -2. Update term's Relationships section with new parent -3. Update old parent's Children list (remove term) -4. Update new parent's Children list (add term) -5. Verify all cross-references still valid after restructure - -**Example**: "Quality Gate" initially under "Process Concepts" moves to "Quality Concepts" after taxonomy refinement - update parent, children, category. - -### Edge Case 3: Term Applies to Multiple Categories - -**When**: Term relevant to multiple categories (e.g., spans Process Concepts and Quality Concepts) - -**Approach**: -1. Assign primary category (where term most naturally fits) -2. Use "Related" field to link to terms in other categories -3. Consider if term should be split into category-specific variants -4. Document cross-category applicability in Usage section - -**Example**: "Validation" applies to both Quality (quality gates) and GitHub (PR validation) - assign to Quality Concepts, link to GitHub-specific validation terms. - -### Edge Case 4: Glossary Growing Beyond Single File - -**When**: Glossary exceeds 1,000+ terms or 10,000+ lines (not currently, but plan ahead) - -**Approach**: -1. Consider splitting by category (one file per category) -2. Create glossary index file linking to category files -3. Maintain alphabetical master index across all files -4. Update maintenance instructions for multi-file structure -5. Preserve single source of truth principle (no duplication) - -**Example**: If glossary reaches 1,500 terms, split into Project-Glossary-PM-Hierarchy.md, Project-Glossary-Process-Concepts.md, etc., with Project-Glossary.md as navigation index. - ---- - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| Cross-reference link broken | Term name changed or typo in anchor | Verify term exists; check anchor format `[[#term-name]]` with hyphens | -| Term not in alphabetical index | Forgot to add to index section | Add term to alphabetical index maintaining alphabetical order | -| Duplicate term definitions | Term added multiple times with slight name variations | Merge duplicates; choose canonical name; add alternate names section | -| Category assignment unclear | Term spans multiple categories | Assign primary category; document cross-category applicability in Usage | -| Wiki submodule not updating | Forgot to commit main repo after wiki push | Run `git add wiki && git commit && git push` in main repo | -| Merge conflict in glossary | Concurrent edits by multiple agents | Pull latest; resolve conflicts preserving both entries; maintain structure | -| Definition too vague | Insufficient context or circular reference | Rewrite with concrete language; link to prerequisite terms | - ---- - -## Related Instructions - -- **See also**: [Work Logging](./work_logging.instructions.md) - Work log entries may surface new terms requiring glossary documentation -- **See also**: [Wiki Workflow](../documentation/wiki_workflow.instructions.md) - Complete GitHub wiki workflow for committing and pushing glossary changes -- **See also**: [Knowledge Preservation Framework](../documentation/knowledge_preservation_framework.instructions.md) - Systematic knowledge capture including terminology documentation -- **See also**: [Task Epic Basics](./task_epic_basics.instructions.md) - PM terminology foundations referenced in glossary -- **Prerequisites**: [Wiki Workflow](../documentation/wiki_workflow.instructions.md) - Understanding wiki operations before maintaining glossary -- **Next steps**: - - [Process Learning Capture](../process/process_learning_capture.instructions.md) - Learning loops surface new terms for glossary - - [Milestone Governance](./milestone_governance.instructions.md) - Milestone completion may introduce new terminology - ---- - -**Success Criteria**: Glossary maintained as authoritative source for PM terminology with complete entries (Definition, Category, Relationships, Usage, Example, See also), bidirectional cross-references, dual-access pattern (category + alphabetical), and immediate updates when new terms introduced. - -**Confidence Check**: Can you explain why terms must appear in both category section and alphabetical index? Do you understand when to update cross-references bidirectionally? Can you articulate the difference between PM terminology and GitHub platform objects? diff --git a/.pongogo/instructions/project_management/scope_creep_prevention.instructions.md b/.pongogo/instructions/project_management/scope_creep_prevention.instructions.md deleted file mode 100644 index 39ac7480..00000000 --- a/.pongogo/instructions/project_management/scope_creep_prevention.instructions.md +++ /dev/null @@ -1,443 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Scope Creep Prevention" -description: "Prevent scope creep through structured boundaries, approval gates, and change management." -applies_to: - - "**/*" -domains: - - "project_management" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 1 - triggers: - keywords: - - scope_creep - - while_we're_at_it - - scope_expansion - - task_boundary - - scope_change - - feature_creep - - out_of_scope - - beyond_scope - nlp: "Scope creep prevention, task boundary enforcement, recognizing and halting scope expansion" -evaluation: - success_signals: - - Scope boundaries identified before work begins - - Danger phrases recognized and halted immediately - - Scope change protocol applied when expansion detected - - Simple tasks stay simple (audit only audits, fix only fixes) - - Task completion matches original objective - failure_signals: - - Scope expanded without explicit approval - - Danger phrases ignored ("while we're at it...") - - Multiple objectives combined in single task - - Strategic work in tactical task - - Improvements added without scope change protocol ---- - - -# Scope Creep Prevention - -**Purpose**: Prevent scope expansion through systematic task boundary enforcement ensuring agent-coordinated development maintains focus and delivers predictable outcomes. - -**Philosophy**: TASKS MUST STAY WITHIN STATED SCOPE - NO EXCEPTIONS. Scope expansion, even with good intentions, wastes resources and derails strategic priorities. - ---- - -## When to Apply - -This instruction applies when: - -- **Scenario 1**: Beginning any task execution (validate scope before starting) -- **Scenario 2**: Mid-task when recognizing potential scope expansion ("while we're at it...") -- **Scenario 3**: Receiving feedback suggesting additional work beyond original scope -- **Scenario 4**: Agents proposing "improvements" or "optimizations" not in original requirements -- **Scenario 5**: Code review or PR feedback introducing new requirements - ---- - -## Quick Reference - -**Scope Creep Recognition and Prevention**: - -**1. Danger Phrases** (Immediate Red Flags): -- "While we're at it..." → STOP - Scope expansion signal -- "This would be a good opportunity to..." → STOP - Strategic creep -- "Let's make this more strategic..." → STOP - Framework creep -- "We should optimize this for the future..." → STOP - Redesign creep -- "Since we're already working here..." → STOP - Efficiency trap - -**2. Task Type Boundaries** (Rigid Rules): -``` -Audit Task → Only audit, don't rebuild or optimize -Compliance Task → Only address compliance, don't add features -Documentation Task → Only document existing, don't redesign -Bug Fix Task → Only fix specific bug, don't refactor modules -Infrastructure Task → Only implement stated infra, no "nice to have" -``` - -**3. Scope Change Protocol** (When Expansion Recognized): -``` -Step 1: IMMEDIATELY STOP current work -Step 2: Explain original scope and proposed change to human -Step 3: WAIT for EXPLICIT approval before proceeding -Step 4: If approved → Update task officially (AC, scope boundaries, complexity) -Step 5: If rejected → Return to original scope -``` - -**4. Scope Validation Checklist** (Before Starting): -- [ ] Task title and objective read carefully -- [ ] Specific, limited scope explicitly identified -- [ ] What IS included understood -- [ ] What is NOT included understood -- [ ] Boundaries clear before work begins - -**5. Is This Scope Expansion?** (Decision Tree): -``` -Proposed work beyond original task objective? -├─ YES → SCOPE EXPANSION -│ ├─ Apply scope change protocol -│ └─ Get explicit approval before proceeding -└─ NO → Within original scope - └─ Proceed with implementation -``` - -**6. Common Scope Expansion Patterns**: -``` -Pattern 1: Simple → Complex -- Original: "Add health check endpoint" -- Expanded: "+ readiness + liveness + aggregation" -- **Status**: SCOPE EXPANSION - -Pattern 2: Tactical → Strategic -- Original: "Audit CLI documentation" -- Expanded: "Create CLI documentation framework" -- **Status**: SCOPE EXPANSION - -Pattern 3: Fix → Refactor -- Original: "Fix authentication token expiry bug" -- Expanded: "Redesign entire token management system" -- **Status**: SCOPE EXPANSION - -Pattern 4: Document → Redesign -- Original: "Document API Gateway config options" -- Expanded: "Build interactive configuration tool" -- **Status**: SCOPE EXPANSION -``` - -**7. When to Create Separate Task** (Instead of Expanding): -- Additional features beyond stated requirements -- Strategic improvements ("make it better for future") -- Optimizations not in original acceptance criteria -- Related improvements discovered during work -- **Action**: Complete original task; create new task for additions - ---- - -## Core Principles - -- **Scope Immutability**: Every task has specific, limited objective - expanding scope without explicit approval is process failure -- **Warning Signs Recognition**: Specific phrases and patterns signal scope creep ("while we're at it", "make this more strategic") -- **Simple Tasks Stay Simple**: Audit tasks only audit, compliance tasks only address compliance, bug fixes only fix specific bugs -- **Mandatory Scope Change Protocol**: Recognize expansion, stop work, explain to human, wait for approval, update task officially -- **Agent Boundary Enforcement**: Agents must recognize and halt scope expansion autonomously before human intervention required - -## Step-by-Step Guidance - -1. **Validate Task Scope Before Beginning (Mandatory)** - - Read original task title and objective carefully - - Identify specific, limited scope explicitly - - Note what is included AND what is excluded - - Confirm understanding matches stated scope - - Expected outcome: Clear scope boundaries understood before any work begins - - Rationale: Prevents scope expansion by establishing baseline understanding - -2. **Monitor for Scope Expansion Warning Signs** - - Watch for danger phrases: "while we're at it", "this is a good opportunity to", "let's make this more strategic" - - Recognize patterns: Adding functionality not in original task, implementing strategic improvements in tactical tasks - - Common variation: Combining multiple objectives in single task execution - - Success indicator: Early recognition of scope expansion attempts before significant work invested - -3. **Apply Task Boundary Rules** - - **Audit tasks**: Only audit, don't rebuild or optimize systems - - **Compliance tasks**: Only address compliance requirements, don't add features - - **Documentation tasks**: Only document existing functionality, don't redesign systems - - **Bug fixes**: Only fix specific bug, don't refactor entire modules - - **Infrastructure tasks**: Only implement stated infrastructure, don't add "nice to have" features - - Integration point: Rules prevent common scope expansion patterns - -4. **Execute Scope Change Protocol When Expansion Recognized** - - IMMEDIATELY stop current work when scope expansion recognized - - Explain original scope and proposed change to human clearly - - Wait for EXPLICIT approval before proceeding with expanded scope - - If approved, update task officially (add acceptance criteria, adjust scope boundaries and complexity if applicable) - - If rejected, return to original scope boundaries - - Success indicator: Scope change explicitly approved and documented before proceeding - -5. **Maintain Focus on Original Objective** - - Task completion addresses original objective completely - - No functionality added beyond stated requirements - - Work complexity matches original task assessment - - Success criteria align with original scope - - Expected outcome: Predictable, focused delivery matching original commitment - -## Examples - -### Example 1: Recognizing and Halting Scope Expansion - -```markdown -# Original Task: "Task: Add Health Check Endpoint to API Gateway" - -## Original Scope (from issue description) -- Implement `/health` endpoint returning 200 OK -- Response includes service status field -- No authentication required for health checks -- Endpoint documented in OpenAPI spec - -## Work Begins - Agent Implementation -```typescript -// Implementing health check endpoint -app.get('/health', (req, res) => { - res.status(200).json({ status: 'healthy' }); -}); -``` - -## SCOPE EXPANSION ATTEMPTED -**Agent thinking**: "While implementing health checks, I notice we should also add: -- Readiness checks (separate `/ready` endpoint) -- Liveness checks (separate `/live` endpoint) -- Dependency health checks (verify database, Redis connectivity) -- Detailed status information (uptime, version, memory usage) -- Health check aggregation across all microservices" - -## STOP - Apply Scope Change Protocol - -**Step 1: Recognize scope expansion** -- Original task: Single `/health` endpoint with status field -- Proposed addition: 4 additional endpoints + dependency checks + aggregation -- **This is NOT in original scope** - -**Step 2: Stop work** -- Health check basic implementation complete (matches original scope) -- DO NOT implement readiness/liveness/aggregation without approval - -**Step 3: Explain to human** -"I've completed the original task: `/health` endpoint with status field. While implementing, I recognized potential enhancements (readiness checks, dependency health, aggregation) that would expand scope significantly. Should I: -1. Mark current task complete as-is (original scope satisfied) -2. Create new task for enhanced observability (scope expansion) -3. Modify current task scope with approval (requires scope change)" - -**Step 4: Wait for approval** -[Human responds: "Complete current task as-is. Create separate task for enhanced observability in Milestone 3."] - -**Step 5: Execute decision** -- Mark original task complete (original scope satisfied) -- Create new task: "Enhanced Health Check Observability" in Milestone 3 -- Document relationship: New task builds on completed task -``` - -**Context**: Agent recognizes scope expansion during implementation and halts before proceeding. Scope change protocol applied systematically, preventing wasted effort. - -**Expected Result**: Original task completed within scope; enhanced features properly scoped as separate task with strategic timing. - -### Example 2: Danger Phrases and Scope Creep Patterns - -```markdown -## Scenario: "Task: Audit CLI Command Documentation" - -### SCOPE CREEP EXAMPLES - -**Danger Phrase 1**: "While we're at it, we could also..." -- "While auditing docs, we could also *rewrite command descriptions* for better clarity" -- **Problem**: Audit scope only, not rewrite -- **Boundary**: Document what's missing/incorrect; don't rewrite content - -**Danger Phrase 2**: "This would be a good opportunity to..." -- "Auditing CLI docs is a good opportunity to *standardize all documentation formats* across services" -- **Problem**: Standardization is separate strategic initiative, not audit task -- **Boundary**: Focus on CLI docs only; standardization requires separate task - -**Danger Phrase 3**: "We should make this more strategic..." -- "Instead of just auditing, we should *create comprehensive CLI documentation framework* for future extensibility" -- **Problem**: Framework creation is strategic work beyond audit scope -- **Boundary**: Audit existing docs; framework is Epic-level work requiring separate planning - -**Danger Phrase 4**: "Let's optimize this for the future..." -- "Let's not just audit but *redesign documentation structure* for better agent discoverability" -- **Problem**: Redesign is architectural work, not audit -- **Boundary**: Audit identifies issues; redesign addressed in separate task - -### CORRECT SCOPE ADHERENCE - -**Original Scope**: Audit CLI command documentation for completeness and accuracy - -**Execution**: -1. Review all CLI commands listed in docs -2. Verify each command documented with usage examples -3. Check for missing commands not documented -4. Identify incorrect or outdated information -5. Create report listing findings (missing, incorrect, outdated) - -**Outcome**: Report delivered with audit findings. Remediation work scoped as separate tasks based on findings. -``` - -**Context**: Common danger phrases signal scope creep. Agent recognizes patterns and maintains audit-only boundary. - -**Trade-offs**: Identifying improvement opportunities feels productive, but scope adherence delivers predictable results without resource waste. - -### Example 3: Simple Tasks Stay Simple - -```markdown -## Task Type: Bug Fix - -**Original Task**: "Fix authentication token expiry bug where tokens expire 1 hour early" - -### SCOPE CREEP -- Fixing bug reveals authentication service could be *refactored for better architecture* -- "While fixing expiry, let's *redesign entire token management system*" -- "This bug indicates we should *implement comprehensive auth refactoring Epic*" - -### CORRECT SCOPE -- Investigate token expiry calculation -- Identify bug: timezone offset not accounted in expiry calculation -- Fix calculation to include timezone offset -- Add test validating timezone handling -- Deploy fix and verify tokens expire at correct time - -**Outcome**: Bug fixed, token expiry works correctly. If refactoring needed, create separate Epic with proper scoping. - ---- - -## Task Type: Documentation - -**Original Task**: "Document API Gateway configuration options" - -### SCOPE CREEP -- "While documenting config, let's *redesign configuration system* for better usability" -- "Documentation reveals we should *create configuration management service*" -- "Let's not just document but *build interactive configuration tool*" - -### CORRECT SCOPE -- List all configuration options from config schema -- Document each option: description, type, default value, examples -- Organize documentation by configuration category -- Include validation rules and constraints -- Publish documentation in docs/reference/api-gateway-config.md - -**Outcome**: Configuration documented. System improvements scoped separately if justified. -``` - -**Context**: Simple task categories (bug fixes, documentation, audits) have clear boundaries. Scope discipline prevents expansion into strategic work. - -**Expected Result**: Tasks completed quickly and predictably within stated boundaries; strategic improvements addressed through proper planning process. - -## Validation Checklist - -- [ ] Task scope read and understood before beginning work (title, objectives, acceptance criteria) -- [ ] Scope boundaries identified (what IS included, what is NOT included) -- [ ] Danger phrases monitored during execution ("while we're at it", "good opportunity to") -- [ ] Task type boundary rules applied (audit only audits, bug fix only fixes bug) -- [ ] Scope expansion recognized if attempted (work proposed beyond original scope) -- [ ] Scope change protocol executed if expansion occurred (stop, explain, wait for approval) -- [ ] Task completion matches original objective (no added functionality without approval) -- [ ] Work complexity matches original assessment (simple tasks stayed simple) -- [ ] Success criteria aligned with original scope (not expanded criteria) - -## Common Pitfalls - -### Pitfall 1: "Improving" Task Scope Without Permission - -- **Problem**: Agent recognizes improvement opportunity and implements it believing it adds value, but work was outside original scope -- **Why it happens**: Good intentions ("making things better") without understanding scope discipline importance -- **Solution**: Recognize that ANY work beyond stated scope requires explicit approval; improvements are scope changes requiring protocol -- **Example**: Task to "add logging" expanded to "add logging + distributed tracing + metrics" - tracing and metrics are scope expansion - -### Pitfall 2: Combining Multiple Objectives in Single Task - -- **Problem**: Task execution addresses original objective PLUS related improvements discovered during work -- **Why it happens**: Efficiency mindset ("since we're already working here, let's fix this too") -- **Solution**: Original objective ONLY; related improvements become separate tasks with proper scoping and prioritization -- **Example**: Fixing authentication bug also refactors auth service architecture - refactoring should be separate task - -### Pitfall 3: Interpreting Simple Tasks as Strategic Opportunities - -- **Problem**: Audit task interpreted as opportunity to redesign system being audited; bug fix seen as refactoring opportunity -- **Why it happens**: Misunderstanding that audit/fix tasks have narrow, tactical scope not strategic scope -- **Solution**: Simple tasks stay simple; strategic work requires strategic planning process (Epic creation, proper scoping) -- **Example**: "Audit API documentation" becomes "Create comprehensive API documentation framework" - framework creation is Epic-level work - -### Pitfall 4: Failing to Recognize Scope Expansion Early - -- **Problem**: Significant work invested in scope expansion before recognizing it's outside original boundaries -- **Why it happens**: Not monitoring for danger phrases or patterns; assuming expanded work is still "related" to original task -- **Solution**: Apply scope validation continuously during execution; stop IMMEDIATELY when expansion recognized -- **Example**: Implementing health checks, then readiness checks, then dependency checks before realizing all beyond original scope - -## Edge Cases - -### Edge Case 1: Scope Clarification vs Scope Expansion - -**When**: Unclear whether proposed work is clarifying ambiguous original scope or expanding beyond stated scope - -**Approach**: -1. Review original task description carefully (what was explicitly stated?) -2. Check acceptance criteria (does proposed work satisfy existing criteria?) -3. If genuinely ambiguous: Ask human for clarification before proceeding -4. If clearly expansion: Apply scope change protocol -5. Document clarification in task comments for future reference - -**Example**: Task says "implement rate limiting" but doesn't specify per-user vs per-IP. Clarifying which type is scope clarification; adding BOTH types is scope expansion. - -### Edge Case 2: Discovered Blocker Requiring Scope Expansion - -**When**: Original task cannot be completed without addressing blocker not anticipated in original scope - -**Approach**: -1. Document blocker clearly (what prevents original task completion?) -2. Determine if blocker is prerequisite or scope expansion -3. If prerequisite: Create separate task for blocker; mark original task blocked -4. If scope expansion disguised as blocker: Apply scope change protocol -5. Update task relationships and dependencies - -**Example**: Implementing rate limiting requires Redis, but Redis not deployed yet. Redis deployment is prerequisite (separate task), not scope expansion of rate limiting task. - -### Edge Case 3: Feedback Introducing New Requirements - -**When**: Code review or PR feedback suggests adding features/changes beyond original acceptance criteria - -**Approach**: -1. Distinguish between feedback on implementation quality vs new requirements -2. Implementation quality feedback (different approach, better code structure) = ACCEPTABLE -3. New requirements (additional features, different functionality) = SCOPE EXPANSION -4. Apply scope change protocol for new requirements -5. Document decision in PR comments - -**Example**: PR feedback "also add metrics endpoint" is new requirement (scope expansion); feedback "use async/await instead of callbacks" is implementation quality (acceptable). - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| Task complexity increased beyond original assessment | Scope expanded during execution without recognition | Audit work performed; identify scope additions; halt expansion; complete original scope only | -| PR includes functionality not in acceptance criteria | Scope creep during implementation | Request PR revision removing out-of-scope work; create separate tasks for additional functionality | -| Agent proposes "improvements" beyond task scope | Good intentions without scope discipline | Recognize as scope expansion; create separate improvement tasks; focus on original scope | -| Simple task becomes complex Epic-level work | Scope expansion through incremental additions | Stop work; decompose into proper Epic with tasks; complete original simple task first | -| Task blocked by "requirements" discovered mid-execution | Unclear whether blocker or scope expansion | Analyze if truly prerequisite or disguised expansion; create separate task for prerequisites | -| Multiple objectives combined in single task | Efficiency mindset overriding scope boundaries | Separate into individual tasks; complete original objective; queue additional work appropriately | - -## Related Instructions - -- **See also**: [Task Epic Basics](./task_epic_basics.instructions.md) - Understanding proper task scoping before execution -- **See also**: [Milestone Governance](./milestone_governance.instructions.md) - Strategic categorization preventing scope misalignment -- **See also**: [Systematic Prevention Framework](../safety_prevention/systematic_prevention_framework.instructions.md) - Systematic approach to preventing scope creep patterns -- **Prerequisites**: [Task Epic Basics](./task_epic_basics.instructions.md) - Understanding task structure and acceptance criteria -- **Next steps**: [Development Workflow Essentials](../trust_execution/development_workflow_essentials.instructions.md) - Completing tasks within scope using trust-based phases - ---- - -**Success Criteria**: All tasks completed within stated scope, scope expansion recognized immediately when attempted, scope change protocol applied systematically, simple tasks stayed simple, and no functionality added beyond original acceptance criteria without explicit approval. - -**Confidence Check**: Can you identify danger phrases signaling scope creep? Do you understand when to apply scope change protocol? diff --git a/.pongogo/instructions/project_management/time_free_project_management.instructions.md b/.pongogo/instructions/project_management/time_free_project_management.instructions.md deleted file mode 100644 index c06ee236..00000000 --- a/.pongogo/instructions/project_management/time_free_project_management.instructions.md +++ /dev/null @@ -1,363 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Time-Free Project Management" -description: "Principles for managing projects without time-based estimates or deadlines." -applies_to: - - "**/*" -domains: - - "project_management" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 1 - triggers: - keywords: - - time_free - - no_estimates - - no_deadlines - - complexity_based - - scope_boundaries - - time_estimate - - commit_driven - nlp: "Time-free project management using complexity-based scoping instead of time estimates, sustainable development" -evaluation: - success_signals: - - Complexity classification used (Simple/Moderate/Complex) - - No time estimates in issues (hours, days, weeks, deadlines) - - Scope boundaries clearly defined (deliverables, constraints) - - Autonomy level appropriate for complexity - - Quality criteria over velocity metrics - failure_signals: - - Time estimates in planning artifacts - - T-shirt sizing as proxy for time (S/M/L hours) - - Deadlines or target dates specified - - Velocity tracking (story points per week) - - Rushing execution to show progress (commit frequency) ---- - - -# Time-Free Project Management - -**Purpose**: Establish project management principles using complexity-based scoping instead of time estimates to enable sustainable, quality-first development. - -**Philosophy**: Sustainable development prioritizes quality and appropriate scoping over time-based metrics and deadlines. - ---- - -## When to Apply - -Use time-free project management when: - -- Creating new issues, epics, or project planning documents -- Reviewing existing templates for time-based language -- Defining task scope and complexity -- Setting work priorities and sequencing -- Evaluating autonomy levels for work items - ---- - -## Quick Reference - -**Key Decision Criteria**: - -**1. Complexity Classification**: -- **Simple**: Established patterns exist, routine operations, standalone work -- **Moderate**: Some new design, multiple integration points, requires judgment calls -- **Complex**: Novel architecture, cross-system dependencies, significant unknowns - -**2. Scope Boundary Questions**: -- What outputs constitute "done"? (deliverables) -- What is explicitly excluded? (constraints) -- What can change vs must remain fixed? (flexibility) - -**3. Autonomy Level Assignment**: -- **Simple** -> Suggest + Confirm (SC): Agent proposes, human approves -- **Moderate** -> Apply + Check (AC): Agent executes, human spot-checks -- **Complex** -> Confirm + Validate (CV): Human involved at multiple checkpoints - -**4. Anti-Pattern Detection**: -- Any mention of hours, days, weeks, sprints, deadlines -- "This should take about..." or "estimated duration" -- Time-based metrics for progress tracking -- Replace with complexity, scope boundaries, quality criteria - ---- - -## Core Principles - -- **No Time Estimates**: Never use hours, weeks, or deadlines in planning or scoping -- **No Estimation Without Measurement**: Never estimate without tracking actuals for comparison -- **Complexity-Based Sizing**: Classify work as Simple, Moderate, or Complex based on decisions and patterns required -- **Scope Boundaries**: Define clear boundaries for autonomous execution without time pressure -- **Quality Over Speed**: Emphasize completeness and correctness over delivery velocity -- **Autonomy Alignment**: Complexity assessment guides appropriate agent autonomy level -- **Execution Pace Freedom**: Time-free applies to execution pace, not just planning - rushing execution violates time-free as much as adding time estimates -- **Minimum Commits, Maximum Completeness**: Commits are publication (completeness), not progress (velocity) - one comprehensive commit is better than multiple incomplete commits - -### Execution Pace and the Time-Free Principle - -**Key Insight**: Time-free principle applies to **execution pace**, not just planning. Rushing through execution violates time-free principles just as much as adding time estimates to tasks. - -**What This Means**: -- Take time to analyze thoroughly before acting -- Complete understanding phase before execution phase -- Single comprehensive pass > multiple rushed passes requiring rework -- Don't optimize for visible progress (commit velocity) -- Don't rush to commit "what I have" before verifying completeness -- Don't treat commit frequency as a success metric - -**Commits Are Not Progress**: -- Commits represent **publication** (complete, reviewed work ready for others) -- Commits do NOT represent **progress** (incremental activity) -- One comprehensive commit demonstrates more competence than three incomplete commits -- Multiple commits for same task = indicator of incomplete analysis - -**Before Committing, Ask**: -1. "Have I systematically reviewed ALL relevant items?" -2. "Have I cross-referenced ALL relevant sources?" -3. "If I commit now, will user need to ask for another pass?" -4. "Am I committing because work is COMPLETE, or because I want to show progress?" - -## Step-by-Step Guidance - -### 1. **Classify Work Complexity** - - Assess pattern availability: Are established patterns available or new design required? - - Evaluate decision complexity: Routine operations vs architectural decisions? - - Consider integration points: Standalone vs multi-system integration? - - Assign complexity: Simple, Moderate, or Complex - - Expected outcome: Clear complexity classification without time estimates - -### 2. **Define Scope Boundaries** - - Identify deliverables: What specific outputs constitute completion? - - Establish constraints: What should explicitly NOT be included? - - Document dependencies: What must be complete before starting? - - Define validation: How will completion be verified? - - Expected outcome: Bounded scope enabling autonomous execution - -### 3. **Determine Autonomy Level** - - Map complexity to autonomy: Simple->Apply, Moderate->Patch, Complex->Propose - - Identify approval gates: What reviews required before progression? - - Document decision authority: What decisions can agent make independently? - - Expected outcome: Appropriate autonomy level for complexity - -### 4. **Remove Time-Based Language** - - Scan for prohibited patterns: "hours", "weeks", "deadline", "time box" - - Replace with complexity assessment: Simple/Moderate/Complex classification - - Update templates: Remove time-based fields from issue templates - - Validate compliance: Grep templates and issues for time references - - Expected outcome: All planning artifacts time-free - -## Examples - -### Example 1: Complexity Classification - -Context: Sizing different types of work - -```markdown -## Simple Complexity Example -**Task**: Add new REST endpoint following existing patterns - -**Why Simple**: -- Routing pattern established -- Authentication middleware available -- Standard CRUD operations -- Existing test templates -- Documentation format defined - -**Autonomy Level**: Apply (bounded) - agent can implement directly -**Approval**: Post-apply review - -## Moderate Complexity Example -**Task**: Implement instruction routing service - -**Why Moderate**: -- Core pattern exists (file path matching) -- Systematic analysis of metadata required -- Integration with MCP server context needed -- New caching strategy required -- Pattern matching edge cases need testing - -**Autonomy Level**: Patch (supervised) - pre-merge review required -**Approval**: Technical review before merge - -## Complex Complexity Example -**Task**: Design autonomy ladder implementation - -**Why Complex**: -- Architectural decisions (propose/patch/apply boundaries) -- Multi-agent coordination patterns undefined -- Approval gate mechanisms need design -- Rollback strategy must be architected -- Security model affects entire system - -**Autonomy Level**: Propose (design) - architecture review required -**Approval**: Design approval before implementation -``` - -**Context**: Guiding task selection and autonomy level determination -**Expected Result**: Clear complexity classification enabling appropriate autonomy - -### Example 2: Template Compliance Correction - -Context: Converting time-based issue template to complexity-based - -```yaml -## BEFORE: Time-Based Template -name: Task -description: Bounded work unit (1-3 hours) -body: - - type: textarea - label: Time Validation - description: Was this actually 1-3 hours of work? - - type: input - label: Estimated Duration - description: How long will this take? - -## AFTER: Complexity-Based Template -name: Task -description: Bounded work unit for agent execution -body: - - type: dropdown - label: Complexity Assessment - options: - - Simple (established patterns) - - Moderate (systematic analysis required) - - Complex (architectural decisions required) - - type: textarea - label: Scope Validation - description: Was the actual work scope aligned with defined boundaries? -``` - -**Context**: Template audit process removing time-based language -**Expected Result**: Compliance with time-free project management principles - -### Example 3: Epic Sizing Without Time Estimates - -Context: Planning authentication epic - -```markdown -## WRONG: Time-Based Approach -Epic: User Authentication (2 weeks) - Task: Implement JWT middleware (4 hours) - Task: Add password hashing (2 hours) - Task: Create login endpoint (3 hours) - Task: Write tests (5 hours) - -## CORRECT: Complexity-Based Approach -Epic: User Authentication (Moderate Complexity) - Task: Implement JWT middleware (Simple - follows Express.js patterns) - - Autonomy: Apply (bounded) - - Scope: JWT validation, token generation, standard claims - - Validation: Tests pass, security review complete - - Task: Add password hashing (Simple - bcrypt library integration) - - Autonomy: Apply (bounded) - - Scope: Hash generation, comparison, salt rounds config - - Validation: Security standards met, tests passing - - Task: Create login endpoint (Moderate - security decisions required) - - Autonomy: Patch (supervised) - - Scope: Credentials validation, session creation, error handling - - Validation: Security review, integration tests, docs updated - - Task: Document authentication flow (Simple - template exists) - - Autonomy: Apply (bounded) - - Scope: API docs, architecture diagrams, usage examples - - Validation: Documentation complete, examples working -``` - -**Context**: Epic decomposition without artificial time pressure -**Expected Result**: Quality-focused scope boundaries with clear autonomy levels - -## Validation Checklist - -Ensure time-free compliance: - -- [ ] No time estimates in issue bodies (hours, days, weeks) -- [ ] No deadlines or target dates specified -- [ ] Complexity assessment included (Simple/Moderate/Complex) -- [ ] Scope boundaries clearly defined -- [ ] Autonomy level appropriate for complexity -- [ ] Approval gates documented -- [ ] Issue templates time-free -- [ ] Validation criteria based on scope not time - -## Common Pitfalls - -### Pitfall 1: Hidden Time Estimates - -- **Problem**: Using T-shirt sizing (S/M/L) as proxy for time estimates -- **Why it happens**: Attempting to preserve velocity calculations -- **Solution**: Use explicit complexity criteria (patterns, decisions, integration) -- **Example**: "Medium task" -> "Moderate complexity requiring systematic analysis of 3 integration points" - -### Pitfall 2: Implicit Deadlines in Priorities - -- **Problem**: Priority labels implying timeframes ("This week", "Next sprint") -- **Why it happens**: Traditional sprint-based planning habits -- **Solution**: Use blocking-based priorities (Critical blocks work, High provides value) -- **Example**: "Sprint priority" -> "Critical - blocks API service deployment" - -### Pitfall 3: Time-Based Scope Validation - -- **Problem**: Asking "Did this take the expected time?" in retrospectives -- **Why it happens**: Attempting to "improve estimates" -- **Solution**: Ask "Was scope aligned with complexity assessment?" -- **Example**: "Took longer than estimated" -> "Complexity was actually higher due to unforeseen integration points" - -### Pitfall 4: Velocity Metrics - -- **Problem**: Tracking "story points per week" or similar velocity measures -- **Why it happens**: Desire for predictability and planning -- **Solution**: Track completion rate by complexity (Simple tasks completed this month) -- **Example**: "15 points per sprint" -> "Completed 8 simple tasks, 3 moderate features" - -## Edge Cases - -### Edge Case 1: External Dependencies with Deadlines - -**When**: Third-party integration has contractual deadline -**Approach**: -- Acknowledge external constraint exists -- Plan work backward from constraint using complexity -- Prioritize critical path items appropriately -- Do not propagate deadline to individual task estimates -- Document constraint as context, not scope - -### Edge Case 2: Marketing or Launch Coordination - -**When**: Feature needs coordination with marketing campaign -**Approach**: -- Document coordination requirement as context -- Identify minimum viable scope for coordination -- Use priority system to sequence work -- Complexity-based planning still applies -- Communicate readiness, not delivery dates - -### Edge Case 3: Regulatory or Compliance Deadlines - -**When**: Legal or regulatory requirement has fixed date -**Approach**: -- Document compliance requirement with legal reference -- Identify scope required for compliance -- Prioritize compliance work as Critical -- Non-compliance work remains complexity-based -- Escalate if complexity assessment indicates risk - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| Agents asking for time estimates | Issue templates still contain time fields | Audit and remove time-based fields | -| Pressure to commit to delivery dates | External stakeholder expectations | Communicate complexity-based approach | -| Difficulty prioritizing without time | Conflating priority with urgency | Use blocking-based priority | -| Templates still reference deadlines | Incomplete template migration | Grep templates for time keywords | -| Scope creep without time bounds | Unclear scope boundaries | Define explicit scope boundaries | - ---- - -**Success Criteria**: All project planning artifacts use complexity-based scoping without time estimates, enabling sustainable development with appropriate autonomy levels and quality-first focus. - -**Confidence Check**: Can you explain scope boundaries without referencing time? Is complexity assessment based on patterns and decisions, not duration? Are approval gates defined by risk, not calendar? diff --git a/.pongogo/instructions/project_management/work_log_monthly_summary.instructions.md b/.pongogo/instructions/project_management/work_log_monthly_summary.instructions.md deleted file mode 100644 index 066f4d22..00000000 --- a/.pongogo/instructions/project_management/work_log_monthly_summary.instructions.md +++ /dev/null @@ -1,397 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Work Log Monthly Summary" -description: "Template and guidance for generating monthly work log summaries." -applies_to: - - "**/*" -domains: - - "project_management" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 1 - triggers: - keywords: - - monthly_summary - - work_log_monthly - - monthly_work_log - - month_summary - - strategic_overview - - project_health - nlp: "Generate monthly summaries from weekly summaries for high-level project overview and strategic context" -evaluation: - success_signals: - - Monthly summary exists for all months with work - - Highlights capture top 3-5 strategic achievements - - Strategic shifts documented with rationale - - Blockers and risks identified (forward-looking) - - Summary fits 50-75 lines per month - failure_signals: - - Missing monthly summary for months with work - - Listing everything instead of strategic significance - - "No forward look (missing Blockers & Risks)" - - Missing week at month boundaries - - Summary too long (loses strategic focus) ---- - - -# Work Log Monthly Summary - -**Purpose**: Generate monthly summaries from weekly summaries, providing high-level project overview and strategic context for quarterly reviews, onboarding, and project health assessment. - -**Philosophy**: Monthly summaries capture the strategic arc of work - what was the focus, what was achieved, what changed. They enable understanding project trajectory without parsing thousands of lines of detail. - ---- - -## When to Apply - -This instruction applies when: - -- **Scenario 1**: First work log entry of a new month (triggers previous month summary) -- **Scenario 2**: Quarterly review or project health assessment -- **Scenario 3**: Backfilling missing monthly summaries -- **Scenario 4**: Onboarding context for new agents/contributors - ---- - -## Trigger Detection - -**Automatic Trigger**: Use MCP time server to determine if summary generation is needed. - -```python -# Check if new month has started -current_date = get_current_date_from_mcp() # e.g., 2025-12-01 - -# If today is first of month and no summary exists for previous month, generate it -if current_date.day == 1: - previous_month = current_date.month - 1 or 12 - previous_year = current_date.year if current_date.month > 1 else current_date.year - 1 - # Check if summary exists for that month, if not, generate -``` - -**Manual Trigger**: When strategic overview is needed and monthly summary doesn't exist. - ---- - -## Quick Reference - -**Monthly Summary File**: `{wiki_path}/Work-Log-Summary.md` (single file, all months) - -**Summary Structure Per Month**: -```markdown -## November 2025 - -### Month at a Glance -- **Primary Focus**: [Main theme of the month] -- **Work Sessions**: NN sessions logged -- **Issues Progressed**: NN issues (NN closed, NN created) -- **Epics**: [Status of active Epics] - -### Highlights -- [Major achievement 1] -- [Major achievement 2] -- [Major achievement 3] - -### Strategic Shifts -- [Any changes to project direction, priorities, or approach] - -### Patterns & Learnings -- [Key patterns extracted or validated] -- [Strategic insights gained] - -### Blockers & Risks -- [Unresolved blockers carried forward] -- [Emerging risks identified] - -### Key Metrics -- Tasks completed: NN -- Retrospectives conducted: NN -- Patterns added to library: NN -- Documentation pages updated: NN -``` - ---- - -## Core Principles - -- **Strategic Focus**: Monthly summaries answer "What happened?" at a strategic level -- **Compression Ratio**: Target 4:1 (4 weekly summaries → 1 monthly section) -- **Trend Emphasis**: Surface patterns across weeks, not individual items -- **Decision Archaeology**: Preserve WHY things changed, not just WHAT changed -- **Actionable Forward**: Note what carries forward to next month - ---- - -## Escalation Criteria (from Weekly to Monthly) - -### 1. Highlights (Top 3-5 Achievements) - -**Definition**: Most significant accomplishments of the month - -**Selection Criteria**: -- Epic completions or major milestones -- Breakthrough moments or key decisions -- External-facing deliverables -- Foundational work enabling future progress - -**Format**: -```markdown -### Highlights -- **Epic Complete**: Routing operationalization achieved with ground truth dataset -- **Tooling Milestone**: /prune-open-issues tool operational after methodology refinement -- **Hierarchical Work Logs**: Infrastructure created to address scalability -``` - -### 2. Strategic Shifts (Direction Changes) - -**Definition**: Changes to project direction, priorities, or approach - -**Examples**: -- Milestone restructuring -- Scope pivots -- Priority reordering -- Methodology changes - -**Format**: -```markdown -### Strategic Shifts -- **Milestone Restructuring**: Legacy milestones closed, priority-based milestones created -- **Milestone Optionality**: Not all issues need milestones (methodology update) -- **Work Log Hierarchy**: Daily → Weekly → Monthly summarization implemented -``` - -### 3. Patterns & Learnings (Knowledge Gained) - -**Definition**: Patterns, insights, and learnings institutionalized - -**Examples**: -- Patterns added to Pattern Library -- Strategic Insights documented -- Process improvements validated -- Anti-patterns identified - -**Format**: -```markdown -### Patterns & Learnings -- 5 patterns extracted from Epic retrospective -- "Umbrella Epic" anti-pattern identified and documented -- Issue triage methodology refined with knowledge-preservation focus -``` - -### 4. Blockers & Risks (Forward-Looking) - -**Definition**: Issues requiring attention in upcoming month - -**Examples**: -- Unresolved blockers -- Technical debt accumulating -- Resource constraints -- Emerging risks - -**Format**: -```markdown -### Blockers & Risks -- **Work Log Size**: 38K+ lines per month unsustainable (addressed via task) -- **Issue Backlog**: 45 unmapped issues pending triage -- **Epic Closure**: Blocked on dependent task completion -``` - ---- - -## Step-by-Step: Generate Monthly Summary - -### 1. Determine Month Boundaries - -```bash -# Get current date from MCP time server -# If first of month, summarize previous month -# Example: December 1 → summarize November 2025 -``` - -### 2. Read Weekly Summaries - -- Open `{wiki_path}/Work-Log-YYYY-MM-Weekly.md` -- Read ALL weekly summaries for the month -- Note week count and total entry counts - -### 3. Aggregate by Category - -For each category, aggregate across all weeks: -- Highlights: Select top 3-5 most significant -- Strategic Shifts: Consolidate all direction changes -- Patterns & Learnings: List all new knowledge -- Blockers & Risks: Identify unresolved items - -### 4. Calculate Metrics - -From weekly summaries and issue tracking: -- Total sessions logged -- Issues progressed (closed, created) -- Retrospectives conducted -- Patterns added -- Documentation updates - -### 5. Write Monthly Section - -Add to `{wiki_path}/Work-Log-Summary.md`: -```markdown -## November 2025 - -### Month at a Glance -... - -### Highlights -... - -[etc.] - ---- -``` - -### 6. Commit and Push - -```bash -cd {wiki_path} -git add Work-Log-Summary.md -git commit -m "Add monthly summary: November 2025" -git push -``` - ---- - -## File Structure - -**Work-Log-Summary.md** (monthly summaries): -```markdown -# Work Log Summary - -This document provides monthly summaries of project development work. - -For weekly detail: See `Work-Log-YYYY-MM-Weekly.md` -For daily detail: See `Work-Log-YYYY-MM.md` - ---- - -## November 2025 -[Latest month first] - ---- - -## October 2025 -[Previous months follow] -``` - ---- - -## Template - -```markdown -## [Month Year] - -### Month at a Glance -- **Primary Focus**: [1-2 sentence description of month's main theme] -- **Work Sessions**: NN sessions logged across NN days -- **Issues Progressed**: NN issues (NN closed, NN created, NN in progress) -- **Epics Active**: [List active Epics with brief status] - -### Highlights -1. [Most significant achievement] -2. [Second most significant] -3. [Third most significant] - -### Strategic Shifts -- **[Topic]**: [What changed and why] -- **[Topic]**: [What changed and why] - -### Patterns & Learnings -- [Pattern or insight gained] -- [Pattern or insight gained] - -### Blockers & Risks -- **[Blocker]**: [Status and forward action] -- **[Risk]**: [What to watch for] - -### Key Metrics -| Metric | Count | -|--------|-------| -| Tasks Completed | NN | -| Retrospectives | NN | -| Patterns Added | NN | -| Instruction Files Updated | NN | -| Wiki Pages Updated | NN | - -### Weeks Summary -- Week 48 (Nov 25-Dec 1): [Brief theme] -- Week 47 (Nov 18-24): [Brief theme] -- Week 46 (Nov 11-17): [Brief theme] -- Week 45 (Nov 4-10): [Brief theme] -- Week 44 (Oct 28-Nov 3): [Brief theme - partial] - ---- -``` - ---- - -## Gap Handling - -**No Work Done**: If a month has no entries: -```markdown -## November 2025 - -*No work logged this month.* - ---- -``` - -**Partial Month** (e.g., project started mid-month): -```markdown -### Month at a Glance -- **Primary Focus**: Project initialization -- **Work Sessions**: 5 sessions logged (Oct 27-31 only) -- **Note**: Project started October 27, 2025 -``` - ---- - -## Validation Checklist - -- [ ] All weekly summaries for month reviewed -- [ ] Top 3-5 highlights selected -- [ ] Strategic shifts documented with rationale -- [ ] Patterns and learnings aggregated -- [ ] Blockers and risks identified (forward-looking) -- [ ] Metrics calculated accurately -- [ ] Week themes summarized -- [ ] Summary fits in ~50-75 lines -- [ ] Navigation links work -- [ ] File committed and pushed - ---- - -## Common Pitfalls - -### Pitfall 1: Missing Weeks at Month Boundaries -- **Problem**: Week starting in Oct but mostly in Nov gets missed -- **Solution**: Check weekly file for cross-boundary weeks - -### Pitfall 2: Listing Everything -- **Problem**: Monthly summary is just a list of everything done -- **Solution**: Focus on STRATEGIC significance, not completeness - -### Pitfall 3: No Forward Look -- **Problem**: Summary only looks backward, misses blockers/risks -- **Solution**: Always include "Blockers & Risks" for continuity - ---- - -## Related Instructions - -- **Child**: [Weekly Summary](work_log_weekly_summary.instructions.md) - Source for monthly aggregation -- **Grandchild**: [Work Logging](work_logging.instructions.md) - Daily entry creation -- **Consumer**: Quarterly reviews, project health assessments, onboarding - ---- - -**Success Criteria**: Monthly summaries exist for all months with work, highlights capture strategic achievements, shifts documented with rationale, patterns preserved, risks surfaced, and summary enables understanding project trajectory in under 75 lines per month. diff --git a/.pongogo/instructions/project_management/work_log_weekly_summary.instructions.md b/.pongogo/instructions/project_management/work_log_weekly_summary.instructions.md deleted file mode 100644 index 6b189087..00000000 --- a/.pongogo/instructions/project_management/work_log_weekly_summary.instructions.md +++ /dev/null @@ -1,387 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Work Log Weekly Summary" -description: "Template and guidance for generating weekly work log summaries." -applies_to: - - "**/*" -domains: - - "project_management" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 1 - triggers: - keywords: - - weekly_summary - - work_log_weekly - - weekly_work_log - - week_summary - - hierarchical_summarization - - weekly_escalation - nlp: "Generate weekly summaries from daily work log entries for cross-referencing and trend analysis" -evaluation: - success_signals: - - Weekly summary exists for all weeks with work - - Critical items escalated (blockers, incidents, decisions) - - Major work chunks summarized with status - - Trends and themes identified across days - - Summary fits 50-100 lines per week - failure_signals: - - Missing weekly summary for weeks with work - - Over-compression losing important context - - Missing cross-month week handling - - No gap notation for empty weeks - - Missing strategy notes (direction changes) ---- - - -# Work Log Weekly Summary - -**Purpose**: Generate weekly summaries from detailed daily work log entries, enabling manageable cross-referencing and trend analysis without requiring full work log parsing. - -**Philosophy**: Hierarchical summarization preserves institutional knowledge while making it accessible. Weekly summaries bridge the gap between detailed daily entries (too granular for context windows) and monthly overviews (too compressed for specific queries). - ---- - -## When to Apply - -This instruction applies when: - -- **Scenario 1**: First work log entry of a new week (Monday or first entry after Sunday) -- **Scenario 2**: Process requires work log cross-reference (e.g., issue triage, retrospectives) -- **Scenario 3**: Backfilling missing weekly summaries -- **Scenario 4**: End of month requiring final week summary - ---- - -## Trigger Detection - -**Automatic Trigger**: Use MCP time server to determine if summary generation is needed. - -```python -# Check if new week has started -from datetime import datetime, timedelta - -current_date = get_current_date_from_mcp() # e.g., 2025-11-29 (Saturday) -week_start = current_date - timedelta(days=current_date.weekday()) # Monday - -# If today is Monday and no summary exists for previous week, generate it -if current_date.weekday() == 0: # Monday - previous_week_end = current_date - timedelta(days=1) # Sunday - previous_week_start = previous_week_end - timedelta(days=6) # Previous Monday - # Check if summary exists for that week, if not, generate -``` - -**Manual Trigger**: When cross-referencing requires weekly summaries that don't exist. - ---- - -## Quick Reference - -**Weekly Summary File**: `{wiki_path}/Work-Log-YYYY-MM-Weekly.md` - -**Week Definition**: Monday through Sunday (ISO week standard) - -**Summary Structure**: -```markdown -## Week of November 25-December 1, 2025 (Week 48) - -### Critical Items -- [Item that requires attention or follow-up] - -### Major Work Completed -- **[Category]**: Brief description of work chunk -- **[Category]**: Brief description of work chunk - -### Trends & Themes -- [Emerging pattern or recurring topic] - -### Strategy Notes -- [Any strategic decisions, shifts, or clarifications] - -### Key Issues Referenced -- #NNN: Brief status note -- #NNN: Brief status note -``` - ---- - -## Core Principles - -- **Escalation-Based**: Only escalate items meeting criteria (critical, trends, strategy) -- **Week Boundaries**: Monday-Sunday per ISO standard -- **Compression Ratio**: Target 10:1 (10 daily entries → 1 weekly summary section) -- **Traceability**: Reference specific dates/entries for drill-down -- **No Loss**: If unsure whether to include, include with brief note - ---- - -## Escalation Criteria - -### 1. Critical Items (ALWAYS Escalate) - -**Definition**: Items requiring attention beyond the current week - -**Examples**: -- Blockers discovered that affect other work -- Incidents or failures with systemic implications -- Decisions that constrain future options -- Breakthroughs that enable new capabilities - -**Format**: -```markdown -### Critical Items -- **BLOCKER**: Issue blocked by work log size - created task to resolve -- **INCIDENT**: Deployment failure - prevention measures implemented -- **DECISION**: Adopted hierarchical work log summaries (affects all future logging) -``` - -### 2. Major Work Chunks (Summarize) - -**Definition**: Significant work completed during the week - -**Aggregation Rules**: -- Group related entries by Epic/Task/Theme -- Note completion status (started, in progress, complete) -- Include key deliverables or artifacts created - -**Format**: -```markdown -### Major Work Completed -- **Epic Retrospective**: Level 4 retrospective complete, 5 patterns extracted, epic ready for closure -- **Tooling**: /prune-open-issues tool development complete (v1.0 operational) -- **Issue Triage**: Clusters A & B complete (8 issues processed), methodology refined -``` - -### 3. Trends & Themes (Identify) - -**Definition**: Patterns emerging across multiple days/entries - -**Examples**: -- Recurring topics (e.g., "MCP server work dominated week") -- Process patterns (e.g., "methodology refinements in 3 separate sessions") -- Quality patterns (e.g., "5 retrospectives conducted this week") - -**Format**: -```markdown -### Trends & Themes -- Heavy focus on routing operationalization (Epic closure prep) -- Multiple methodology refinements (issue triage, work logging, retrospectives) -- Documentation debt addressed (3 instruction files updated) -``` - -### 4. Strategy Notes (Preserve) - -**Definition**: Higher-order context affecting project direction - -**Examples**: -- Strategic decisions with rationale -- Scope changes or pivots -- Priority shifts -- Architectural clarifications - -**Format**: -```markdown -### Strategy Notes -- **Milestone Optionality**: Established that not all issues need milestones -- **Icebox vs Backlog**: Clarified semantic distinction for issue triage -- **Work Log Hierarchy**: Decided to implement weekly/monthly summaries -``` - ---- - -## Step-by-Step: Generate Weekly Summary - -### 1. Determine Week Boundaries - -```bash -# Get current date from MCP time server -# Calculate week boundaries (Monday-Sunday) -# Example: Week of Nov 25 - Dec 1, 2025 -``` - -### 2. Read Daily Entries for Week - -- Open `{wiki_path}/Work-Log-YYYY-MM.md` -- Read ALL entries for dates within the week -- Note: Week may span two monthly files (e.g., Nov 25 - Dec 1) - -### 3. Extract by Escalation Criteria - -For each entry, ask: -- [ ] Is this critical? (blocker, incident, constraining decision, breakthrough) -- [ ] Is this major work? (significant deliverable, milestone progress) -- [ ] Does this contribute to a trend? (recurring topic, pattern) -- [ ] Is this strategy-relevant? (decision, pivot, priority change) - -### 4. Aggregate and Compress - -- Group related items -- Summarize multi-entry work into single bullets -- Preserve key details, drop routine information -- Target: ~50-100 lines per week - -### 5. Add to Weekly Summary File - -```markdown -# Work Log Weekly Summaries - November 2025 - -## Week of November 25-December 1, 2025 (Week 48) - -### Critical Items -- ... - -### Major Work Completed -- ... - -### Trends & Themes -- ... - -### Strategy Notes -- ... - -### Key Issues Referenced -- ... - ---- - -## Week of November 18-24, 2025 (Week 47) -... -``` - -### 6. Commit and Push - -```bash -cd {wiki_path} -git add Work-Log-2025-11-Weekly.md -git commit -m "Add weekly summary: Week 48 (Nov 25 - Dec 1)" -git push -``` - ---- - -## File Structure - -**Monthly Detail File** (existing): `{wiki_path}/Work-Log-YYYY-MM.md` -- Contains all daily entries -- Reverse chronological within each day -- No changes to existing structure - -**Weekly Summary File** (new): `{wiki_path}/Work-Log-YYYY-MM-Weekly.md` -- One file per month containing all weeks -- Weeks in reverse chronological order (newest first) -- Links back to daily detail for drill-down - -**Cross-Month Weeks**: When a week spans two months (e.g., Nov 25 - Dec 1): -- Summary appears in the file for the month containing Monday -- Example: Week of Nov 25 - Dec 1 → `Work-Log-2025-11-Weekly.md` - ---- - -## Template - -```markdown -# Work Log Weekly Summaries - [Month Year] - -Navigation: [Monthly Summary](Work-Log-Summary) | [Daily Detail](Work-Log-YYYY-MM) - ---- - -## Week of [Start Date]-[End Date], [Year] (Week NN) - -### Critical Items -- [None this week / List critical items] - -### Major Work Completed -- **[Category]**: Description -- **[Category]**: Description - -### Trends & Themes -- [Pattern or recurring topic] - -### Strategy Notes -- [Strategic decision or clarification] - -### Key Issues Referenced -- #NNN: Status/outcome -- #NNN: Status/outcome - -### Daily Entry Count -- Monday: N entries -- Tuesday: N entries -- ... -- Sunday: N entries -- **Total**: NN entries → summarized above - ---- - -## Week of [Previous Week] -... -``` - ---- - -## Gap Handling - -**No Work Done**: If a week has no entries: -```markdown -## Week of November 18-24, 2025 (Week 47) - -*No work logged this week.* - ---- -``` - -**Partial Week**: If only some days have entries, summarize what exists and note gaps: -```markdown -### Daily Entry Count -- Monday: 0 entries -- Tuesday: 3 entries -- Wednesday-Sunday: 0 entries -- **Total**: 3 entries (partial week) -``` - ---- - -## Validation Checklist - -- [ ] Week boundaries correct (Monday-Sunday) -- [ ] All daily entries for week reviewed -- [ ] Critical items identified and escalated -- [ ] Major work chunks summarized -- [ ] Trends identified across multiple days -- [ ] Strategy notes preserved -- [ ] Key issues referenced with status -- [ ] Summary fits in ~50-100 lines -- [ ] Links to daily detail work correctly -- [ ] File committed and pushed - ---- - -## Common Pitfalls - -### Pitfall 1: Missing Cross-Month Week -- **Problem**: Week spans Nov-Dec but only Nov entries reviewed -- **Solution**: Always check both monthly files for weeks at month boundaries - -### Pitfall 2: Over-Compression -- **Problem**: Summary loses important context trying to be brief -- **Solution**: When uncertain, include more detail; monthly summary will compress further - -### Pitfall 3: Missing Gap Notation -- **Problem**: Week with no entries has no entry in weekly file -- **Solution**: Always create week section, noting "No work logged" if empty - ---- - -## Related Instructions - -- **Parent**: [Work Logging](work_logging.instructions.md) - Daily entry creation -- **Sibling**: [Monthly Summary](work_log_monthly_summary.instructions.md) - Aggregate from weekly -- **Consumer**: Issue closure workflow - Uses weekly summaries for cross-reference - ---- - -**Success Criteria**: Weekly summaries exist for all weeks with work, critical items escalated, major work visible, trends identified, and files under 200 lines enabling context-window-friendly cross-referencing. diff --git a/.pongogo/instructions/project_management/work_logging.instructions.md b/.pongogo/instructions/project_management/work_logging.instructions.md deleted file mode 100644 index de3a05ce..00000000 --- a/.pongogo/instructions/project_management/work_logging.instructions.md +++ /dev/null @@ -1,438 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Work Logging" -description: "Work logging standards and entry format for project management context." -applies_to: - - "**/*" -domains: - - "project_management" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 1 - triggers: - keywords: - - work_log - - work_logging - - add_work_log_entry - - work_log_entry - - progress_tracking - - institutional_knowledge - - two-level_learning - nlp: "Work logging, progress tracking, and institutional knowledge capture through wiki integration" -evaluation: - success_signals: - - Wiki repository validated before adding entry - - Entry at TOP of date section (reverse chronological) - - "Bidirectional links created (wiki <-> GitHub)" - - Two-level learning captured (content + process) - - Changes committed and pushed immediately - failure_signals: - - Skipping wiki validation before entry - - Entry appended to bottom (chronological order) - - "One-way linking (wiki -> GitHub only)" - - Missing sidebar update on first entry of day - - Forgetting to push after commit ---- - - -# Work Logging - -**Purpose**: Establish systematic work logging capturing development progress, strategic decisions, and institutional knowledge through wiki integration for agent and human reference. - -**Philosophy**: Work logs are living memory - comprehensive, timely entries enable agents to understand project context and make informed decisions without manual lookup. Work logs capture both what we learned (content) and how we learned it (process meta-knowledge). - ---- - -## When to Apply - -This instruction applies when: - -- **Scenario 1**: Completing significant development work (Epic tasks, milestones, architectural decisions) -- **Scenario 2**: Documenting strategic decisions or technical investigations -- **Scenario 3**: Recording milestone progress or Epic completion validation -- **Scenario 4**: Capturing lessons learned or systematic improvements -- **Scenario 5**: Creating institutional knowledge reference for future work - ---- - -## Work Log Entry Timing - -**Single Entry Per Task/Issue Pattern** (PREFERRED): -- Create work log entry **during learning loop execution** (at task completion) -- Entry captures: Implementation summary, decisions, learnings, evidence, commits -- Status note: "Awaiting approval" at time of entry -- **No separate closure entry needed** - closure is administrative - -**When Closure Entry IS Valuable** (EXCEPTION): -- Significant delay between completion and closure (days/weeks) -- New learnings discovered during review process -- Significant changes made based on user feedback -- In these cases: Update original entry OR create addendum - -**Anti-Pattern to Avoid**: -- Completion entry + Closure entry = Redundant information -- Two entries documenting same deliverables/commits/evidence -- Single comprehensive entry at completion captures all necessary context - ---- - -## Quick Reference - -**Most Common Patterns**: - -**1. Basic Work Log Entry Format**: -```markdown -### 04:15 PM [milestone] -#### Epic Validation Complete -Description of work completed... -``` - -**2. Entry with Two-Level Learning**: -```markdown -### 02:45 PM [development] -#### Feature Implementation Complete -Main description of work... - -**LEARNING (Level 1 - Content)**: -- Technical knowledge gained -- Patterns discovered - -**LEARNING (Level 2 - Process)**: -- Decision-making insights -- Collaboration patterns observed -``` - -**3. Bidirectional Linking**: -```markdown -See [GitHub Issue #45](https://github.com/{org}/{repo}/issues/45) - -# In GitHub Issue #45: -Work Log: [Oct 27 Entry](https://github.com/{org}/{repo}/wiki/Work-Log-2025-10#october-27-2025) -``` - -**4. Check if First Entry of Day** (Bash): -```bash -DATE_LINK="[[Oct 27|Work-Log-2025-10#october-27-2025]]" -if ! grep -q "$DATE_LINK" _Sidebar.md; then - echo "Update sidebar with today's date" -fi -``` - -**5. Commit and Push Workflow**: -```bash -cd {wiki_path} -git add . -git commit -m "Add work log entry: [description]" -git push origin master -``` - ---- - -## Core Principles - -- **Wiki-Based System**: Wiki is single source of truth for strategic development tracking -- **Hierarchical Summarization**: Daily -> Weekly -> Monthly summaries enable both detail and overview -- **Monthly Work Log Files**: Entries organized in monthly files (Work-Log-YYYY-MM.md) with structured format -- **Reverse Chronological Order**: Newest entries at top within date sections for easy discovery -- **Bidirectional Linking**: Link from wiki to GitHub artifacts AND mirror links back from GitHub to wiki -- **Immediate Commit and Push**: All wiki changes committed and pushed immediately -- **Two-Level Learning Capture**: Every work log entry captures both content learning (what we learned) and process learning (how we learned it) - ---- - -## Hierarchical Work Log System - -Work logs use a 3-tier hierarchy to balance detail with accessibility: - -| Level | File | Content | Use Case | -|-------|------|---------|----------| -| **Daily** | `Work-Log-YYYY-MM.md` | Full detail entries | Real-time capture, session reference | -| **Weekly** | `Work-Log-YYYY-MM-Weekly.md` | Escalated summaries | Cross-referencing, trend analysis | -| **Monthly** | `Work-Log-Summary.md` | Strategic overview | Project health, onboarding, reviews | - -### Why Hierarchical? - -**Problem**: Monthly work logs can exceed 30,000+ lines, making them: -- Impossible to fit in agent context windows -- Impractical for cross-referencing during processes like issue triage -- Difficult to identify patterns and trends - -**Solution**: Generate weekly and monthly summaries with escalation criteria: - -1. **Critical Items**: Blockers, incidents, constraining decisions, breakthroughs -2. **Major Work Chunks**: Significant deliverables grouped by Epic/Task/Theme -3. **Trends & Themes**: Patterns emerging across multiple days/entries -4. **Strategy Notes**: Direction changes, priorities, approach shifts - -### Compression Ratios - -- **Weekly**: ~10:1 (10 daily entries -> 1 summary section, ~50-100 lines) -- **Monthly**: ~4:1 (4 weekly summaries -> 1 monthly section, ~50-75 lines) - ---- - -## Two-Level Learning Capture - -Work logs must capture **two distinct types of learning** at every moment of analysis: - -### Level 1: Content Learning (What We Learned) -**Definition**: Knowledge gained from the work product itself - -**Examples**: -- "Cognitive load is reduced by 78% when agents load focused files vs comprehensive files" -- "Batch processing in migrations avoids table locks" -- "Security patterns consolidated from 3 files into 1 focused file" - -**Captured in**: Main entry description, technical details, outcomes - -### Level 2: Process Learning (How We Learned) -**Definition**: Meta-knowledge about the process, collaboration, and decision-making - -**Examples**: -- "User's correction about evaluation criteria led to better analysis" -- "Effective feedback pattern: state real criteria explicitly, explain rationale" -- "After decision pivots, user requests execution confirmation" -- "Solo founder context means long-term quality trumps short-term speed" - -**Captured in**: "LEARNING:" tagged sections, process insights, collaboration patterns - -### Why Both Levels Matter - -**Content learning alone** builds knowledge base and improves technical quality but doesn't improve how we work together or evolve collaboration patterns. - -**Process learning added** enables continuous improvement of: -- Collaboration patterns and effective communication -- Decision-making frameworks -- Human-agent interaction quality -- System-level evolution - -### How to Capture in Work Logs - -**Format for entries with significant learnings**: -```markdown -### HH:MM AM/PM [tag] -#### Entry Title -Main description of work completed, decisions made, outcomes achieved. - -**LEARNING (Level 1 - Content)**: -- Technical knowledge gained -- Patterns discovered -- Measurable outcomes - -**LEARNING (Level 2 - Process)**: -- Decision-making insights -- Collaboration patterns observed -- Effective feedback moments -- Workflow evolution -- Meta-knowledge about how we worked -``` - -**When to include learning capture**: -- Significant decisions or pivots -- User corrective feedback received -- New collaboration patterns discovered -- Workflow improvements identified -- Gap recognition in process -- NOT for routine technical updates (unless process insights) - -## Step-by-Step Guidance - -1. **Validate Wiki Repository (Mandatory First Step)** - - Check if wiki repository exists at `{wiki_path}/` - - Update to latest version with `git pull origin master` - - Verify work log files accessible (Work-Log-YYYY-MM.md for current month) - - Expected outcome: Wiki repository validated and current before adding entry - -2. **Get Validated Timestamp** - - Use time service or system time with timezone awareness - - Validate timezone offset matches project timezone - - Format: HH:MM AM/PM (12-hour format for readability) - - Success indicator: Timestamp accurate and timezone-consistent - -3. **Create Work Log Entry** - - Navigate to current month's work log (e.g., Work-Log-2025-10.md) - - Find or create date section (e.g., `## October 27, 2025`) - - Insert entry at TOP of date section (reverse chronological order) - - Follow format: `### HH:MM AM/PM [tag]` then `#### Title` then description - - Common variation: Entry titles should be 3-6 words for scannability - -4. **Update Sidebar (First Entry of Day Only)** - - Check if current date already exists in `_Sidebar.md` - - If missing (first entry of day), add date link at top of sidebar section - - Maintain maximum 4-5 recent dates; remove oldest if needed - - Success indicator: Sidebar provides quick navigation to recent work - -5. **Apply Bidirectional Linking** - - Link from wiki entry to GitHub issues, PRs, commits - - Add wiki URL to referenced GitHub artifact (issue body or comment) - - Use full URLs for GitHub artifacts (not relative references) - - Expected outcome: Agents can traverse context in both directions - -6. **Commit and Push Immediately** - - Stage changes: `git add .` - - Commit with descriptive message: `git commit -m "Add work log entry: [brief description]"` - - Push to remote: `git push origin master` - - Success indicator: Changes visible in GitHub wiki interface immediately - -## Examples - -### Example 1: Work Log Entry with Two-Level Learning - -```markdown -## October 27, 2025 - -### 02:45 PM [milestone] -#### P3 File Creation Complete -Completed creation of 5 P3 optimization files (observability, CI/CD, security, -database migrations, performance) totaling ~2,750 lines. All files follow -consistent structure with comprehensive examples, machine-readable validation -checklists, and systematic prevention patterns. - -**LEARNING (Level 1 - Content)**: -- Focused P3 files reduce cognitive waste from 78% to 5% (94% improvement) -- Routing confidence improves from 0.70 to 0.95 (36% increase) with domain-specific files -- P3 files have highest systematic prevention density (65% vs 58% in P0) -- All 5 optimization domains covered: observability, CI/CD, security, DB migrations, performance - -**LEARNING (Level 2 - Process)**: -- User corrected evaluation criteria: Real metric is "cognitive load on agents at run-time" - not "time to create files" -- User emphasized: Quality and completeness now, since speed isn't the concern -- Decision-making insight: Solo founder context means long-term quality > short-term speed -- Effective feedback pattern: User stated real criteria explicitly, explained rationale, - let agent re-analyze with correct criteria -- Collaboration pattern: After decision pivot, user asked "is this proceeding?" to verify - execution starting (not just planning) -``` - -**Context**: This entry demonstrates both content learning and process learning. -**Expected Result**: Future agents can learn what was built AND how decisions were made. - -### Example 2: Event Tag Usage - -```markdown -## October 27, 2025 - -### 04:15 PM [milestone] -#### Validation Framework Complete -Completed Epic validation standards... - -### 02:30 PM [architecture] -#### Routing Service Design -Finalized instruction routing service architecture. Decision: Use Redis cache -with 5-minute TTL based on instruction update frequency analysis... - -### 11:00 AM [development] -#### API Gateway Rate Limiting -Implemented token bucket rate limiting with Redis state storage. Achieves -< 5ms latency for rate limit checks... - -### 09:15 AM [analysis] -#### Cache Performance Investigation -Analyzed cache hit rates across services. Findings: Routing service 87% hit rate, -instruction registry 92% hit rate... - ---- - -## October 26, 2025 - -### 05:30 PM [documentation] -#### Instruction File Standards -Updated documentation standards with path reference guidelines... -``` - -**Context**: Event tags categorize entries enabling filtering and pattern recognition. -**Expected Result**: Agents and humans can quickly identify entry types. - -## Validation Checklist - -- [ ] Wiki repository validated before adding entry (exists, up-to-date, accessible) -- [ ] Timestamp obtained with timezone validation -- [ ] Entry added to correct monthly file (Work-Log-YYYY-MM.md) -- [ ] Date section found or created (## Month DD, YYYY) -- [ ] Entry inserted at TOP of date section (reverse chronological order) -- [ ] Entry format correct (### Time [tag], #### Title, description) -- [ ] Title concise (3-6 words for scannability) -- [ ] Bidirectional links created (wiki -> GitHub, GitHub -> wiki) -- [ ] **Two-level learning captured (if significant work)**: - - [ ] Level 1 (Content): Technical knowledge, patterns discovered, measurable outcomes - - [ ] Level 2 (Process): Decision-making insights, collaboration patterns, meta-learning -- [ ] Sidebar updated if first entry of day (date link added) -- [ ] All changes committed with descriptive message -- [ ] Changes pushed to remote wiki immediately - -## Common Pitfalls - -### Pitfall 1: Skipping Wiki Validation - -- **Problem**: Attempting to add work log entry without validating wiki repository exists -- **Why it happens**: Assumption that wiki is always available -- **Solution**: ALWAYS run validation protocol first; clone if missing; pull latest changes - -### Pitfall 2: Forgetting Sidebar Update on First Entry of Day - -- **Problem**: Adding first work log entry for new date but not updating sidebar -- **Why it happens**: Focus on entry content without remembering sidebar maintenance -- **Solution**: Check sidebar for current date link; if missing, add at top - -### Pitfall 3: One-Way Linking (Wiki -> GitHub Only) - -- **Problem**: Work log entry links to GitHub issue but issue doesn't link back to wiki -- **Why it happens**: Focus on wiki documentation without considering GitHub as reference point -- **Solution**: ALWAYS create bidirectional links - -### Pitfall 4: Appending Entries to Bottom (Chronological Order) - -- **Problem**: Adding new entries at bottom of date section instead of top -- **Why it happens**: Habit from traditional log files -- **Solution**: ALWAYS insert at TOP of date section; newest entries appear first - -## Edge Cases - -### Edge Case 1: First Entry of New Month - -**When**: Adding first work log entry for new month requires creating new file -**Approach**: -1. Create new file following naming convention (e.g., Work-Log-2025-11.md) -2. Copy structure from previous month (breadcrumb navigation, metadata) -3. Update month references in navigation and metadata -4. Add first date section and entry -5. Update Work-Log.md index with link to new month -6. Update sidebar with new month section - -### Edge Case 2: Multiple Entries Same Day from Different Agents - -**When**: Multiple agents adding work log entries to same date section concurrently -**Approach**: -1. First agent adds entry, commits, and pushes -2. Second agent pulls latest changes before adding entry -3. If merge conflict, resolve by preserving both entries in reverse chronological order -4. Commit merge resolution with both entries included -5. Push to remote - -### Edge Case 3: Long Entry Requiring Multiple Paragraphs - -**When**: Work log entry content requires substantial detail -**Approach**: -1. Keep entry format (### time [tag], #### title) but expand description -2. Use paragraphs, bullet points, code blocks as needed for clarity -3. Consider linking to separate documentation for extensive technical detail -4. Balance between comprehensive wiki entry and linking to detailed docs - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| Wiki directory doesn't exist | Repository not cloned yet | Run validation protocol; clone from GitHub | -| Work log file missing | Wrong month or file not created yet | Create new monthly file | -| Sidebar date links broken | Date anchor format incorrect | Use format: `[[Mon DD\|Work-Log-YYYY-MM#month-dd-yyyy]]` | -| Entry not visible after push | Push failed or incomplete | Verify push completed without errors | -| Merge conflict during push | Concurrent edits | Pull latest; resolve conflicts; commit and push | -| Duplicate date sections | Didn't check for existing section | Search for date pattern before creating | - ---- - -**Success Criteria**: Work log entries added to wiki with validated timestamps, proper formatting, bidirectional links to GitHub artifacts, **two-level learning captured for significant work (content + process)**, sidebar updated for first entry of day, and changes committed and pushed immediately. diff --git a/.pongogo/instructions/quality/environment_configuration.instructions.md b/.pongogo/instructions/quality/environment_configuration.instructions.md deleted file mode 100644 index 3700b49f..00000000 --- a/.pongogo/instructions/quality/environment_configuration.instructions.md +++ /dev/null @@ -1,930 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Environment Configuration" -description: "Environment configuration standards, validation, and consistency patterns." -applies_to: - - "**/*" -domains: - - "quality" -priority: "P1" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 1 - triggers: - keywords: - - environment_configuration - - env_file - - .env - - config_validation - - secrets_management - - environment_variables - - dotenv - - pydantic_config - - zod_config - - type-safe_config - - fail_fast_config - nlp: "Environment configuration management including .env patterns, config validation, secrets management" -evaluation: - success_signals: - - Config validated at startup with Zod/Pydantic before any operations - - Service fails fast with clear error on missing required variables - - .env.example documents all variables with descriptions and examples - - .env files in .gitignore, secrets never committed to git - - Type-safe config module exports validated typed config object - failure_signals: - - Service runs with defaults for missing critical config (silent failure) - - Secrets committed to git history (DATABASE_URL with password) - - process.env accessed directly throughout codebase (not centralized) - - No .env.example file documenting required variables - - Config validation at runtime instead of startup (late failures) ---- - - -# Environment Configuration Standards - -**Purpose**: Establish comprehensive environment configuration management ensuring secure, validated, environment-specific settings with systematic prevention of configuration errors. - -**Philosophy**: Configuration is code - validate it, version it (except secrets), and fail fast on misconfiguration rather than running with defaults. - ---- - -## When to Apply - -Use these configuration standards when: - -- Setting up new services or environments -- Adding environment variables -- Managing secrets and credentials -- Configuring service dependencies -- Deploying to different environments - ---- - -## Quick Reference - -**Key Environment Configuration Patterns (Code Examples)**: - -**1. .env.example Template**: -```bash -# .env.example -# Copy to .env and fill in values -# DO NOT commit .env with real secrets - -# ===== Service Configuration ===== -NODE_ENV=development -PORT=3000 -LOG_LEVEL=info - -# ===== Database ===== -# Format: postgresql://user:password@host:port/database -DATABASE_URL=postgresql://postgres:postgres@localhost:5432/{project} -DATABASE_POOL_SIZE=10 - -# ===== External Services ===== -KNOWLEDGE_SERVICE_URL=http://knowledge-service:3000 - -# ===== Feature Flags ===== -ENABLE_DEBUG_ENDPOINTS=true - -# ===== Security ===== -# API_KEY=your-secret-api-key-here -CORS_ALLOWED_ORIGINS=http://localhost:3000 - -# ===== Observability ===== -# SENTRY_DSN=https://... -ENABLE_METRICS=false -METRICS_PORT=9090 -``` - -**2. Type-Safe Config (TypeScript + Zod)**: -```typescript -// services/routing/src/config.ts -import { z } from 'zod'; -import dotenv from 'dotenv'; - -dotenv.config(); - -const ConfigSchema = z.object({ - nodeEnv: z.enum(['development', 'staging', 'production']).default('development'), - port: z.coerce.number().int().min(1).max(65535).default(3000), - logLevel: z.enum(['debug', 'info', 'warn', 'error']).default('info'), - - // Required - will fail if missing - databaseUrl: z.string().url(), - knowledgeServiceUrl: z.string().url(), - - // Optional with defaults - routingConfidenceThreshold: z.coerce.number().min(0).max(1).default(0.5), - - // Boolean from string - enableDebugEndpoints: z - .string() - .transform((val) => val === 'true') - .default('false'), -}); - -export type Config = z.infer; - -function loadConfig(): Config { - try { - return ConfigSchema.parse({ - nodeEnv: process.env.NODE_ENV, - port: process.env.PORT, - databaseUrl: process.env.DATABASE_URL, - // ... all env vars - }); - } catch (error) { - console.error('❌ Configuration validation failed:'); - // Print helpful error messages - process.exit(1); - } -} - -export const config = loadConfig(); -``` - -**3. Type-Safe Config (Python + Pydantic)**: -```python -# services/routing/config.py -from pydantic import BaseSettings, Field -from typing import Optional -from dotenv import load_dotenv - -load_dotenv() - -class Config(BaseSettings): - """Application configuration with validation.""" - - # Service - node_env: str = Field(default="development") - port: int = Field(default=3000, ge=1, le=65535) - - # Database (required) - database_url: str = Field(..., env="DATABASE_URL") - database_pool_size: int = Field(default=10, ge=1, le=100) - - # Feature flags - enable_debug_endpoints: bool = Field(default=False) - - # Security - api_key: Optional[str] = Field(None) - - @validator("api_key") - def validate_api_key_in_production(cls, v, values): - """Require API key in production.""" - if values.get("node_env") == "production" and not v: - raise ValueError("api_key required in production") - return v - - class Config: - env_file = ".env" - -# Load configuration (fails fast if invalid) -config = Config() -``` - -**4. Environment-Specific Configs**: -```typescript -// config/production.ts -export const productionConfig = { - database: { - poolSize: 20, - ssl: true, // Always in production - }, - features: { - debugEndpoints: false, // Never in production - detailedErrors: false, // Hide errors - }, - cache: { - ttl: 600, // 10 minutes - }, -}; - -// config/development.ts -export const developmentConfig = { - database: { - poolSize: 5, - ssl: false, - }, - features: { - debugEndpoints: true, // Enable in dev - detailedErrors: true, // Show full errors - }, - cache: { - ttl: 60, // 1 minute - }, -}; -``` - -**5. Config Validation Tests**: -```typescript -describe('Config', () => { - test('fails with missing required DATABASE_URL', () => { - delete process.env.DATABASE_URL; - - expect(() => { - require('./config'); - }).toThrow(/database_url/i); - }); - - test('fails with invalid PORT number', () => { - process.env.PORT = '70000'; // > 65535 - - expect(() => { - require('./config'); - }).toThrow(/port/i); - }); - - test('uses default values for optional config', () => { - const { config } = require('./config'); - expect(config.port).toBe(3000); - expect(config.logLevel).toBe('info'); - }); -}); -``` - -**6. .gitignore for Config**: -```gitignore -# NEVER commit real secrets -.env -.env.local -.env.production -.env.staging - -# DO commit example (no real secrets) -# .env.example ← This should be committed - -# Config with secrets -config/local.json -config/production.json -config/secrets.yaml - -# DO commit config templates -# config/template.json -# config/example.yaml -``` - -**7. Config Loading Checklist**: -```typescript -// At service startup: -// 1. Load environment variables -dotenv.config(); - -// 2. Validate config (fail fast) -const config = loadConfig(); - -// 3. Log config (without secrets) -logger.info('Config loaded', { - nodeEnv: config.nodeEnv, - port: config.port, - // NEVER log: apiKey, databaseUrl with password -}); - -// 4. Check critical dependencies -await checkDatabaseConnection(); -await checkExternalServices(); - -// 5. Start service -app.listen(config.port); -``` - ---- - -## Core Principles - -- **Never Commit Secrets**: Use .env files, never commit to git -- **Validate at Startup**: Check all required env vars before running -- **Fail Fast on Missing**: No silent defaults for critical config -- **.env.example Committed**: Document all required variables -- **Type-Safe Config**: Validate types, not just presence -- **Environment-Specific**: dev/staging/production configs separated -- **Documentation Required**: Comment purpose of each variable -- **Defaults for Non-Secrets**: Reasonable defaults for non-critical config - -## Step-by-Step Guidance - -### 1. **Define Required Variables** - - List all environment variables needed - - Categorize: secrets, URLs, feature flags, tuning - - Document purpose and valid values - - Expected outcome: Complete list of required config - -### 2. **Create .env.example** - - Document all variables with descriptions - - Include example values (not real secrets) - - Commit to git for documentation - - Expected outcome: Developers know what config needed - -### 3. **Implement Config Validation** - - Load variables at startup - - Validate presence of required vars - - Validate types and formats - - Fail with clear error if invalid - - Expected outcome: Service won't start with bad config - -### 4. **Use Config Module** - - Centralize config loading in one module - - Export typed config object - - Single source of truth - - Expected outcome: Config accessed through typed module - -### 5. **Add to .gitignore** - - Ensure .env files in .gitignore - - Never commit actual secrets - - Use .env.example for documentation - - Expected outcome: Secrets never in git history - -### 6. **Document Deployment** - - Document how to set env vars in production - - Kubernetes secrets, AWS Parameter Store, etc. - - Include in deployment docs - - Expected outcome: Clear deployment process - -### 7. **Test Config Validation** - - Test service fails with missing vars - - Test service fails with invalid types - - Test defaults work correctly - - Expected outcome: Config validation tested - -## Examples - -### Example 1: .env.example Template - -Comprehensive .env.example: - -```bash -# .env.example -# Copy this file to .env and fill in values -# DO NOT commit .env file with real secrets - -# ===== Service Configuration ===== -# Node environment (development, staging, production) -NODE_ENV=development - -# Service port -PORT=3000 - -# Log level (debug, info, warn, error) -LOG_LEVEL=info - -# ===== Database Configuration ===== -# PostgreSQL connection string -# Format: postgresql://user:password@host:port/database -DATABASE_URL=postgresql://postgres:postgres@localhost:5432/{project}_routing - -# Database connection pool size -DATABASE_POOL_SIZE=10 - -# ===== External Services ===== -# Knowledge service URL -KNOWLEDGE_SERVICE_URL=http://knowledge-service:3000 - -# Orchestration service URL (optional for standalone mode) -# ORCHESTRATION_SERVICE_URL=http://orchestration-service:3000 - -# ===== Feature Flags ===== -# Enable debug endpoints (true/false) - ONLY true in development -ENABLE_DEBUG_ENDPOINTS=true - -# Enable request correlation IDs (true/false) -ENABLE_CORRELATION_IDS=true - -# ===== Routing Configuration ===== -# Minimum confidence threshold for returning matches (0.0-1.0) -ROUTING_CONFIDENCE_THRESHOLD=0.5 - -# Maximum number of results to return -ROUTING_MAX_RESULTS=10 - -# Cache TTL for metadata in seconds -ROUTING_CACHE_TTL=300 - -# ===== Security ===== -# API key for external requests (required in production) -# API_KEY=your-secret-api-key-here - -# CORS allowed origins (comma-separated) -CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001 - -# ===== Observability ===== -# Sentry DSN for error tracking (optional) -# SENTRY_DSN=https://... - -# Enable metrics export (true/false) -ENABLE_METRICS=false - -# Metrics export port -METRICS_PORT=9090 -``` - -**Context**: Complete .env.example documents all configuration -**Expected Result**: Developers understand all config requirements - -### Example 2: Type-Safe Config Module (TypeScript) - -Validated, typed configuration: - -```typescript -// services/routing/src/config.ts - -import { z } from 'zod'; -import dotenv from 'dotenv'; - -// Load environment variables -dotenv.config(); - -/** - * Configuration schema with validation. - */ -const ConfigSchema = z.object({ - // Service - nodeEnv: z.enum(['development', 'staging', 'production']).default('development'), - port: z.coerce.number().int().min(1).max(65535).default(3000), - logLevel: z.enum(['debug', 'info', 'warn', 'error']).default('info'), - - // Database - databaseUrl: z.string().url(), - databasePoolSize: z.coerce.number().int().min(1).max(100).default(10), - - // External Services - knowledgeServiceUrl: z.string().url(), - orchestrationServiceUrl: z.string().url().optional(), - - // Feature Flags - enableDebugEndpoints: z - .string() - .transform((val) => val === 'true') - .default('false'), - enableCorrelationIds: z - .string() - .transform((val) => val === 'true') - .default('true'), - - // Routing Configuration - routingConfidenceThreshold: z.coerce.number().min(0).max(1).default(0.5), - routingMaxResults: z.coerce.number().int().min(1).max(100).default(10), - routingCacheTtl: z.coerce.number().int().min(0).default(300), - - // Security - apiKey: z.string().optional(), - corsAllowedOrigins: z - .string() - .transform((val) => val.split(',')) - .default('http://localhost:3000'), - - // Observability - sentryDsn: z.string().url().optional(), - enableMetrics: z - .string() - .transform((val) => val === 'true') - .default('false'), - metricsPort: z.coerce.number().int().min(1).max(65535).default(9090), -}); - -/** - * Validated configuration type. - */ -export type Config = z.infer; - -/** - * Load and validate configuration. - * Throws error if configuration invalid. - */ -function loadConfig(): Config { - try { - const config = ConfigSchema.parse({ - nodeEnv: process.env.NODE_ENV, - port: process.env.PORT, - logLevel: process.env.LOG_LEVEL, - databaseUrl: process.env.DATABASE_URL, - databasePoolSize: process.env.DATABASE_POOL_SIZE, - knowledgeServiceUrl: process.env.KNOWLEDGE_SERVICE_URL, - orchestrationServiceUrl: process.env.ORCHESTRATION_SERVICE_URL, - enableDebugEndpoints: process.env.ENABLE_DEBUG_ENDPOINTS, - enableCorrelationIds: process.env.ENABLE_CORRELATION_IDS, - routingConfidenceThreshold: process.env.ROUTING_CONFIDENCE_THRESHOLD, - routingMaxResults: process.env.ROUTING_MAX_RESULTS, - routingCacheTtl: process.env.ROUTING_CACHE_TTL, - apiKey: process.env.API_KEY, - corsAllowedOrigins: process.env.CORS_ALLOWED_ORIGINS, - sentryDsn: process.env.SENTRY_DSN, - enableMetrics: process.env.ENABLE_METRICS, - metricsPort: process.env.METRICS_PORT, - }); - - return config; - } catch (error) { - if (error instanceof z.ZodError) { - console.error('❌ Configuration validation failed:'); - console.error(''); - - error.errors.forEach((err) => { - const envVar = err.path.join('_').toUpperCase(); - console.error(` ${envVar}: ${err.message}`); - }); - - console.error(''); - console.error('Please check your .env file and ensure all required variables are set.'); - console.error('See .env.example for reference.'); - - process.exit(1); - } - - throw error; - } -} - -/** - * Validated configuration object. - * Use this throughout the application. - */ -export const config = loadConfig(); - -/** - * Check if running in production. - */ -export const isProduction = config.nodeEnv === 'production'; - -/** - * Check if running in development. - */ -export const isDevelopment = config.nodeEnv === 'development'; -``` - -**Context**: Type-safe config with validation at startup -**Expected Result**: Service fails fast with clear error on misconfiguration - -### Example 3: Python Config with Pydantic - -Type-safe Python configuration: - -```python -# services/routing/config.py - -from pydantic import BaseSettings, Field, validator -from typing import Optional, List -import os -from dotenv import load_dotenv - -# Load .env file -load_dotenv() - - -class Config(BaseSettings): - """ - Application configuration with validation. - - All settings loaded from environment variables. - """ - - # Service - node_env: str = Field(default="development", env="NODE_ENV") - port: int = Field(default=3000, ge=1, le=65535, env="PORT") - log_level: str = Field(default="info", env="LOG_LEVEL") - - # Database - database_url: str = Field(..., env="DATABASE_URL") # Required - database_pool_size: int = Field(default=10, ge=1, le=100) - - # External Services - knowledge_service_url: str = Field(..., env="KNOWLEDGE_SERVICE_URL") - orchestration_service_url: Optional[str] = Field(None) - - # Feature Flags - enable_debug_endpoints: bool = Field(default=False) - enable_correlation_ids: bool = Field(default=True) - - # Routing Configuration - routing_confidence_threshold: float = Field(default=0.5, ge=0.0, le=1.0) - routing_max_results: int = Field(default=10, ge=1, le=100) - routing_cache_ttl: int = Field(default=300, ge=0) - - # Security - api_key: Optional[str] = Field(None) - cors_allowed_origins: str = Field(default="http://localhost:3000") - - # Observability - sentry_dsn: Optional[str] = Field(None) - enable_metrics: bool = Field(default=False) - metrics_port: int = Field(default=9090, ge=1, le=65535) - - @validator("log_level") - def validate_log_level(cls, v): - """Validate log level is valid.""" - valid_levels = ["debug", "info", "warn", "error"] - if v.lower() not in valid_levels: - raise ValueError(f"log_level must be one of {valid_levels}") - return v.lower() - - @validator("node_env") - def validate_node_env(cls, v): - """Validate node environment.""" - valid_envs = ["development", "staging", "production"] - if v.lower() not in valid_envs: - raise ValueError(f"node_env must be one of {valid_envs}") - return v.lower() - - @validator("api_key") - def validate_api_key_in_production(cls, v, values): - """Require API key in production.""" - if values.get("node_env") == "production" and not v: - raise ValueError("api_key required in production") - return v - - @property - def is_production(self) -> bool: - """Check if running in production.""" - return self.node_env == "production" - - @property - def is_development(self) -> bool: - """Check if running in development.""" - return self.node_env == "development" - - @property - def cors_origins_list(self) -> List[str]: - """Get CORS origins as list.""" - return [origin.strip() for origin in self.cors_allowed_origins.split(",")] - - class Config: - env_file = ".env" - env_file_encoding = "utf-8" - case_sensitive = False # Allow case-insensitive env vars - - -# Load and validate configuration -try: - config = Config() -except Exception as e: - print(f"❌ Configuration validation failed: {e}") - print("") - print("Please check your .env file and ensure all required variables are set.") - print("See .env.example for reference.") - exit(1) -``` - -**Context**: Pydantic validates Python config with types -**Expected Result**: Clear validation errors on startup - -### Example 4: Environment-Specific Configs - -Separate configs for different environments: - -```typescript -// services/routing/src/config/index.ts - -import { developmentConfig } from './development'; -import { stagingConfig } from './staging'; -import { productionConfig } from './production'; - -export interface ServiceConfig { - database: { - url: string; - poolSize: number; - ssl: boolean; - }; - cache: { - ttl: number; - maxSize: number; - }; - features: { - debugEndpoints: boolean; - detailedErrors: boolean; - }; -} - -const NODE_ENV = process.env.NODE_ENV || 'development'; - -/** - * Get configuration for current environment. - */ -export function getConfig(): ServiceConfig { - switch (NODE_ENV) { - case 'production': - return productionConfig; - case 'staging': - return stagingConfig; - case 'development': - default: - return developmentConfig; - } -} - -// services/routing/src/config/production.ts -export const productionConfig: ServiceConfig = { - database: { - url: process.env.DATABASE_URL!, - poolSize: 20, - ssl: true, - }, - cache: { - ttl: 600, // 10 minutes - maxSize: 10000, - }, - features: { - debugEndpoints: false, // Never in production - detailedErrors: false, // Hide errors in production - }, -}; - -// services/routing/src/config/development.ts -export const developmentConfig: ServiceConfig = { - database: { - url: process.env.DATABASE_URL || 'postgresql://localhost/{project}_dev', - poolSize: 5, - ssl: false, - }, - cache: { - ttl: 60, // 1 minute - maxSize: 100, - }, - features: { - debugEndpoints: true, // Enable in dev - detailedErrors: true, // Show full errors in dev - }, -}; -``` - -**Context**: Environment-specific configs with appropriate defaults -**Expected Result**: Safe defaults per environment - -### Example 5: Config Validation Tests - -Test config validation: - -```typescript -// services/routing/src/config.test.ts - -describe('Config', () => { - const originalEnv = process.env; - - beforeEach(() => { - jest.resetModules(); - process.env = { ...originalEnv }; - }); - - afterEach(() => { - process.env = originalEnv; - }); - - test('loads valid config successfully', () => { - process.env.DATABASE_URL = 'postgresql://localhost/test'; - process.env.KNOWLEDGE_SERVICE_URL = 'http://localhost:3000'; - - const { config } = require('./config'); - - expect(config.databaseUrl).toBe('postgresql://localhost/test'); - expect(config.knowledgeServiceUrl).toBe('http://localhost:3000'); - }); - - test('fails with missing required DATABASE_URL', () => { - delete process.env.DATABASE_URL; - process.env.KNOWLEDGE_SERVICE_URL = 'http://localhost:3000'; - - expect(() => { - require('./config'); - }).toThrow(); - }); - - test('fails with invalid PORT number', () => { - process.env.PORT = '70000'; // Invalid: > 65535 - process.env.DATABASE_URL = 'postgresql://localhost/test'; - process.env.KNOWLEDGE_SERVICE_URL = 'http://localhost:3000'; - - expect(() => { - require('./config'); - }).toThrow(/port/i); - }); - - test('uses default values for optional config', () => { - process.env.DATABASE_URL = 'postgresql://localhost/test'; - process.env.KNOWLEDGE_SERVICE_URL = 'http://localhost:3000'; - - const { config } = require('./config'); - - expect(config.port).toBe(3000); - expect(config.logLevel).toBe('info'); - expect(config.routingConfidenceThreshold).toBe(0.5); - }); - - test('parses boolean environment variables correctly', () => { - process.env.DATABASE_URL = 'postgresql://localhost/test'; - process.env.KNOWLEDGE_SERVICE_URL = 'http://localhost:3000'; - process.env.ENABLE_DEBUG_ENDPOINTS = 'true'; - - const { config } = require('./config'); - - expect(config.enableDebugEndpoints).toBe(true); - }); -}); -``` - -**Context**: Test config validation catches issues -**Expected Result**: Config validation tested and working - -## Validation Checklist - -For configuration setup: - -- [ ] .env.example created with all variables documented -- [ ] .env added to .gitignore -- [ ] Config validation implemented (zod/pydantic) -- [ ] Service fails fast on missing required config -- [ ] Type-safe config module created -- [ ] All secrets loaded from env vars (never hardcoded) -- [ ] Reasonable defaults for non-secrets -- [ ] Config validation tested -- [ ] Environment-specific configs separated -- [ ] Deployment documentation includes env var setup - -## Common Pitfalls - -### Pitfall 1: Committing Secrets - -- ❌ **Problem**: .env file with secrets committed to git -- **Why it happens**: Forgetting .gitignore -- ✅ **Solution**: Add .env to .gitignore, commit .env.example only -- **Example**: DATABASE_URL with password in git history - -### Pitfall 2: Silent Defaults for Critical Config - -- ❌ **Problem**: Service runs with wrong config, fails later -- **Why it happens**: Using defaults for required vars -- ✅ **Solution**: Fail fast at startup if required vars missing -- **Example**: DATABASE_URL defaults to localhost, connects to wrong DB - -### Pitfall 3: No Config Validation - -- ❌ **Problem**: Invalid config (wrong type, invalid value) causes runtime errors -- **Why it happens**: Not validating config at startup -- ✅ **Solution**: Use zod/pydantic to validate types and constraints -- **Example**: PORT="abc" passes, crashes later - -### Pitfall 4: Missing .env.example - -- ❌ **Problem**: Developers don't know what config needed -- **Why it happens**: Not documenting required variables -- ✅ **Solution**: Commit .env.example with all variables and descriptions -- **Example**: New developer can't start service - -### Pitfall 5: Environment Variables in Code - -- ❌ **Problem**: `process.env.VAR` scattered throughout codebase -- **Why it happens**: Not using centralized config module -- ✅ **Solution**: Load env vars once in config module, import typed config -- **Example**: Can't mock config in tests - -## Edge Cases - -### Edge Case 1: Config Changes Requiring Restart - -**When**: Environment variables changed after service started -**Approach**: -- Document that service restart required -- Consider hot-reload for non-critical config -- Use feature flags for runtime toggles -**Example**: Changing log level requires restart - -### Edge Case 2: Secret Rotation - -**When**: API keys/passwords need to be rotated -**Approach**: -- Document rotation process -- Use secrets manager (AWS Secrets Manager, HashiCorp Vault) -- Support grace period with both old and new keys -**Example**: DATABASE_PASSWORD changed, need rolling deployment - -### Edge Case 3: Multi-Tenant Configuration - -**When**: Same service serves multiple tenants with different config -**Approach**: -- Base config from env vars -- Tenant-specific overrides from database/config service -- Clear precedence: tenant > env > defaults -**Example**: Per-tenant API rate limits - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| Service won't start | Missing required env var | Check error message, add var to .env | -| Config validation fails | Invalid value or type | Fix value in .env to match schema | -| Secrets exposed in logs | Logging config object | Filter secrets before logging | -| Different behavior locally vs prod | Different env vars | Document all env vars in .env.example | -| Can't test with different config | Config loaded at module level | Make config injectable for testing | -| Service uses wrong DB | Wrong DATABASE_URL | Check .env file, verify config loading | -| Secrets committed to git | .env not in .gitignore | Add to .gitignore, rotate secrets, remove from history | - -## Related Instructions - -- **See also**: [systematic_prevention_framework.instructions.md](../safety_prevention/systematic_prevention_framework.instructions.md) - Prevent config errors systematically -- **See also**: [agent_environment_setup.instructions.md](../agentic_workflows/agent_environment_setup.instructions.md) - Zero-config service setup -- **Related**: [dependency_management.instructions.md](./dependency_management.instructions.md) - Managing config dependencies - ---- - -**Success Criteria**: All config validated at startup, .env.example documents all variables, secrets never committed, service fails fast on misconfiguration, config module is type-safe. - -**Confidence Check**: Is config validated at startup? Does .env.example exist and document all variables? Are secrets in .gitignore? Does service fail clearly on missing config? diff --git a/.pongogo/instructions/quality/pull_request_workflow.instructions.md b/.pongogo/instructions/quality/pull_request_workflow.instructions.md deleted file mode 100644 index ba01b245..00000000 --- a/.pongogo/instructions/quality/pull_request_workflow.instructions.md +++ /dev/null @@ -1,701 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Pull Request Workflow" -description: "Pull request workflow with mandatory review checklist and quality gates." -applies_to: - - "**/*" -domains: - - "quality" -priority: "P1" -pongogo_version: "2026-02-12" -source: "Original" - -enforcement: - scope: session - blocked_tools: - - mutating - blocked_until: - - action_type: read_instruction -routing: - priority: 1 - triggers: - keywords: - - pull_request - - PR_workflow - - PR_template - - PR_description - - CI_quality_gates - - squash_merge - - small_focused_PR - - PR_checklist - - merge_decision - - feature_branch - nlp: "Pull request workflow standards including creation, description templates, CI gates, review process, and quality gates" -evaluation: - success_signals: - - PR uses template with complete description - - PR linked to GitHub issue - - CI gates passing before review requested - - PR size under 400 lines (focused change) - - Squash merge with clean commit message - failure_signals: - - PR created without template or description - - CI failing when review requested - - Large multi-purpose PR (2000+ lines) - - Force-push during active review - - PR not linked to issue ---- - - -# Pull Request Workflow Standards - -**Purpose**: Establish comprehensive PR workflow ensuring quality, traceability, and systematic integration of changes through standardized processes and quality gates. - -**Philosophy**: PRs are quality checkpoints - every PR represents complete, tested, reviewed work ready for production. - ---- - -## When to Apply - -Use this PR workflow when: - -- Creating pull requests for any code changes -- Preparing features, bug fixes, or refactorings for review -- Integrating work into main branch -- Setting up CI/CD quality gates - ---- - -## Quick Reference - -**Key PR Workflow Patterns (Templates & Process)**: - -**1. PR Description Template**: -```markdown -## Summary -[1-3 sentence description of what this PR does] - -Fixes #[issue-number] - -## Changes -- Added confidence scoring to routing service -- Implemented pattern matching -- Added integration tests - -## Test Plan -- [x] Unit tests added/updated -- [x] Integration tests added/updated -- [x] Manual testing completed -- [x] All tests passing -- [x] CI passing - -## Checklist -- [x] Code follows style guide -- [x] Tests added for new functionality -- [x] Type checking passes -- [x] Linting passes -- [x] Documentation updated -- [x] No breaking changes - -🤖 Generated with Claude Code using Claude Sonnet 4.5 - -Co-Authored-By: Claude Sonnet 4.5 -``` - -**2. PR Title Format**: -``` -# Format: [type] Brief description (#issue) - -✅ Good: -feat: Add confidence scoring to routing (#123) -fix: Handle null values in pattern matcher (#124) -refactor: Extract validation logic (#125) -docs: Update API documentation (#126) -test: Add integration tests (#127) -chore: Update dependencies (#128) - -❌ Bad: -Update code -Fix bug -Changes -``` - -**3. Small, Focused PR Guidelines**: -``` -❌ BAD: Large PR -Files: 45 changed -Lines: +2,847 / -1,234 -Scope: Feature + refactor + docs + fixes - -✅ GOOD: Small PRs -PR 1: feat: Pattern matching (#123) - Files: 5, Lines: +287 / -12 - -PR 2: refactor: Extract types (#124) - Files: 8, Lines: +156 / -203 - -PR 3: docs: API documentation (#125) - Files: 2, Lines: +89 / -3 - -Target: <400 lines per PR -``` - -**4. CI Quality Gates**: -```yaml -# Required checks before merge: - -✓ Type Check (tsc --noEmit) -✓ Lint (npm run lint) -✓ Unit Tests (npm test) -✓ Integration Tests (npm run test:integration) -✓ Build (npm run build) -✓ Coverage ≥80% - -# All must pass ✅ before merge allowed -``` - -**5. PR Workflow Timeline**: -``` -Day 0: Create PR → Self-Review → Fix CI - │ - ├─ Draft PR for WIP - └─ Ready for Review when CI green - -Day 1: Request Review (within 24h) - │ - ├─ Reviewer 1: Approve ✅ - └─ Reviewer 2: Request Changes 🔄 - -Day 2: Address Feedback → Push Changes - │ - └─ Re-request Review - -Day 2-3: Final Approval → Merge - │ - ├─ Squash and Merge (preferred) - └─ Delete Branch -``` - -**6. Review Response Pattern**: -```markdown -# Reviewer: "Consider extracting this function" - -❌ Bad: "It's fine." - -✅ Good: "Great suggestion! Extracted to -`validateRequest()` in commit abc123. -Now easier to test. LMKIF!" -``` - -**7. Pre-PR Self-Review Checklist**: -```bash -# Before creating PR: -git diff main...HEAD # Review all changes -npm run typecheck # Check types -npm run lint # Check style -npm test # Run tests -git log --oneline # Review commits - -# Remove before committing: -- console.log / debugger statements -- Commented-out code blocks -- TODOs without GitHub issues -- Unused imports -- Debug configuration -``` - -**8. Merge Decision Tree**: -``` -Ready to merge? -├─ CI passing? NO → Fix CI first -├─ 2+ approvals? NO → Wait for approvals -├─ All feedback addressed? NO → Address comments -├─ Conflicts? YES → Resolve conflicts -└─ All YES → ✅ Squash and Merge - └─ Delete branch after merge -``` - -**9. Common PR Commands**: -```bash -# Create PR via CLI -gh pr create --title "feat: Add feature" --body-file pr-template.md - -# Checkout PR for review -gh pr checkout 123 - -# Check PR status -gh pr view 123 - -# List open PRs -gh pr list - -# Merge PR (after approval) -gh pr merge 123 --squash --delete-branch - -# Re-request review after changes -gh pr ready 123 -``` - ---- - -## Core Principles - -- **Small, Focused PRs**: One logical change per PR (<400 lines preferred) -- **Complete Context**: PR description explains what, why, and how -- **CI Gates Pass**: All tests, linting, type checking pass before review -- **Self-Review First**: Review own changes before requesting review -- **Draft for WIP**: Use draft PRs for work-in-progress, convert when ready -- **Link to Issues**: Every PR links to GitHub issue/task -- **Machine-Readable Checklists**: Use checkboxes for validation steps -- **Squash-Merge Preferred**: Clean commit history on main - -## Step-by-Step Guidance - -### 1. **Create Feature Branch** - - Branch from main: `git checkout -b feature/routing-confidence-scoring` - - Use descriptive branch names: `feature/`, `fix/`, `refactor/` - - Expected outcome: Feature branch created from latest main - -### 2. **Make Commits** - - Small, logical commits with clear messages - - Follow commit message format (see git_safety.instructions.md) - - Run tests before each commit - - Expected outcome: Clean commit history documenting work - -### 3. **Self-Review Changes** - - Review own diff before creating PR - - Check for debug code, console.logs, TODOs - - Verify tests added/updated - - Run full CI suite locally - - Expected outcome: Changes ready for external review - -### 4. **Create Pull Request** - - Use PR template (see examples) - - Write clear title and description - - Link to GitHub issue - - Add machine-readable checklist - - Request reviewers - - Expected outcome: Complete PR ready for review - -### 5. **Address CI Failures** - - Fix any CI failures immediately - - Don't request review until CI green - - Push fixes, CI re-runs automatically - - Expected outcome: All CI gates passing - -### 6. **Respond to Review Feedback** - - Address all review comments - - Push new commits (don't force-push during review) - - Re-request review after changes - - Expected outcome: All feedback addressed - -### 7. **Merge When Approved** - - Squash and merge (preferred) - - Use generated squash commit message - - Delete branch after merge - - Expected outcome: Changes integrated into main, branch cleaned up - -## Examples - -### Example 1: PR Template - -Standard PR description template: - -```markdown -## Summary - -Brief description of what this PR does (1-3 sentences). - -Fixes #[issue-number] - -## Changes - -- Added confidence scoring to routing service -- Implemented pattern matching with glob library -- Added integration tests for routing endpoint -- Updated API documentation - -## Test Plan - -- [x] Unit tests added/updated -- [x] Integration tests added/updated -- [x] Manual testing completed -- [x] All tests passing locally -- [x] CI pipeline passing - -## Screenshots/Examples - - - - -```bash -# Example API request -curl -X POST http://localhost:3001/v1/route \ - -H "Content-Type: application/json" \ - -d '{"type": "file_path", "value": "services/routing/index.ts"}' - -# Response -{ - "instructions": [ - { - "path": "knowledge/instructions/routing/routing_service.md", - "confidence": 0.95, - "reason": "File path matches applies_to pattern" - } - ] -} -``` - -## Checklist - -- [x] Code follows project style guide -- [x] Tests added for new functionality -- [x] All tests passing (unit + integration) -- [x] Type checking passes (`tsc --noEmit`) -- [x] Linting passes (`npm run lint`) -- [x] Documentation updated -- [x] No breaking changes (or documented if unavoidable) -- [x] Performance impact considered -- [x] Security implications reviewed - -## Deployment Notes - - -- No database migrations required -- No environment variable changes -- Safe to deploy immediately after merge - ---- - -🤖 Generated with Claude Code using Claude Sonnet 4.5 - -Co-Authored-By: Claude Sonnet 4.5 -``` - -**IMPORTANT**: PR descriptions MUST include model attribution for accurate tracking. Model name is read from `~/.claude/settings.json` configuration. - -**Context**: Template provides structure for complete PR descriptions -**Expected Result**: Consistent, comprehensive PR documentation - -### Example 2: PR Title Format - -Clear, descriptive PR titles: - -``` -# Format: [Type] Brief description (#issue-number) - -✅ Good Examples: -feat: Add confidence scoring to routing service (#123) -fix: Handle null values in pattern matcher (#124) -refactor: Extract validation logic into separate module (#125) -docs: Update API documentation for routing endpoint (#126) -test: Add integration tests for semantic matching (#127) -chore: Update dependencies to latest versions (#128) - -❌ Bad Examples: -Update code -Fix bug -Changes -WIP -asdf -``` - -**Context**: Standardized titles enable filtering and changelog generation -**Expected Result**: Scannable PR list, clear purpose at a glance - -### Example 3: Small, Focused PR - -Keep PRs small and focused: - -``` -# ❌ BAD: Large, multi-purpose PR -PR: Implement routing service, refactor types, update docs, fix bugs - -Files changed: 45 -Lines: +2,847 / -1,234 - -Changes: -- New routing service implementation -- Refactored all type definitions -- Updated 15 documentation files -- Fixed 3 unrelated bugs -- Updated dependencies -- Changed logging format - -# ✅ GOOD: Small, focused PRs -PR 1: feat: Implement pattern matching for routing service (#123) -Files changed: 5 -Lines: +287 / -12 - -PR 2: refactor: Extract routing types to shared module (#124) -Files changed: 8 -Lines: +156 / -203 - -PR 3: docs: Add routing service API documentation (#125) -Files changed: 2 -Lines: +89 / -3 - -PR 4: fix: Handle empty file paths in pattern matcher (#126) -Files changed: 2 -Lines: +15 / -8 -``` - -**Context**: Small PRs are easier to review, faster to merge, safer to deploy -**Expected Result**: PRs reviewed same day, less risk - -### Example 4: CI Quality Gates - -Required CI checks before merge: - -```yaml -# .github/workflows/pr-checks.yml -name: PR Quality Gates - -on: - pull_request: - branches: [main] - -jobs: - # Gate 1: Type Checking - typecheck: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 - - run: npm ci - - run: npm run typecheck - # Fail PR if type errors - - # Gate 2: Linting - lint: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 - - run: npm ci - - run: npm run lint - # Fail PR if lint errors - - # Gate 3: Unit Tests - test-unit: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 - - run: npm ci - - run: npm run test:unit - - run: npm run test:coverage - # Fail if coverage < 80% - - # Gate 4: Integration Tests - test-integration: - runs-on: ubuntu-latest - services: - postgres: - image: postgres:16 - env: - POSTGRES_PASSWORD: postgres - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 - - run: npm ci - - run: npm run test:integration - - # Gate 5: Build - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 - - run: npm ci - - run: npm run build - # Fail if build errors - - # All gates must pass for merge - all-checks: - needs: [typecheck, lint, test-unit, test-integration, build] - runs-on: ubuntu-latest - steps: - - run: echo "All quality gates passed ✅" -``` - -**Context**: Automated quality gates prevent broken code merging -**Expected Result**: Only high-quality code reaches main branch - -### Example 5: Review Response Pattern - -Professional review feedback responses: - -```markdown -# Reviewer Comment: -> This function is doing too much. Consider extracting the validation logic. - -# ❌ Bad Response: -"It's fine as is." - -# ✅ Good Response: -"Good catch! I've extracted the validation logic into a separate `validateRequest()` function in commit abc123. The function now has a single responsibility and is easier to test. Let me know if this addresses your concern." - ---- - -# Reviewer Comment: -> What happens if the pattern array is empty? - -# ❌ Bad Response: -"It won't be empty." - -# ✅ Good Response: -"Great question! I've added a guard clause to handle empty arrays (commit def456) and added a test case for this edge case (commit ghi789). The function now returns an empty array if no patterns provided." - ---- - -# Reviewer Comment: -> Can we add types for these parameters? - -# ❌ Bad Response: -"Fixed." - -# ✅ Good Response: -"Absolutely - added full type annotations for all parameters and return type in commit jkl012. Also ran `tsc --noEmit` to verify no type errors." -``` - -**Context**: Clear responses improve collaboration and review efficiency -**Expected Result**: Fast review cycles, mutual learning - -## Validation Checklist - -Before creating PR: - -- [ ] Branch created from latest main -- [ ] Commits are small and logical -- [ ] Commit messages follow format -- [ ] Tests added/updated for changes -- [ ] All tests passing locally -- [ ] Type checking passes -- [ ] Linting passes -- [ ] No debug code (console.log, debugger) -- [ ] No commented-out code -- [ ] No TODOs without GitHub issues -- [ ] Self-reviewed diff - -Before requesting review: - -- [ ] PR description complete (using template) -- [ ] Linked to GitHub issue -- [ ] CI passing (all gates green) -- [ ] Screenshots/examples included (if applicable) -- [ ] Breaking changes documented -- [ ] PR size reasonable (<400 lines preferred) - -Before merging: - -- [ ] All review comments addressed -- [ ] All reviewers approved -- [ ] CI still passing after latest changes -- [ ] Conflicts resolved -- [ ] Squash commit message clean - -## Common Pitfalls - -### Pitfall 1: Large, Multi-Purpose PRs - -- ❌ **Problem**: 2,000+ line PRs mixing features, refactoring, docs -- **Why it happens**: Not breaking work into focused changes -- ✅ **Solution**: One logical change per PR, max 400 lines -- **Example**: PR with new feature + refactoring + bug fixes - -### Pitfall 2: Creating PR with Failing CI - -- ❌ **Problem**: Requesting review while CI red -- **Why it happens**: Not running tests locally first -- ✅ **Solution**: Fix CI before requesting review -- **Example**: PR with failing tests, reviewer wastes time - -### Pitfall 3: Vague PR Descriptions - -- ❌ **Problem**: PR title "Update code" with no description -- **Why it happens**: Not using PR template -- ✅ **Solution**: Use template, explain what/why/how -- **Example**: Reviewer can't understand purpose of changes - -### Pitfall 4: Force-Pushing During Review - -- ❌ **Problem**: Force-push rewrites history, breaks review flow -- **Why it happens**: Trying to clean up commits during review -- ✅ **Solution**: Add new commits during review, squash at merge -- **Example**: Reviewer loses track of what changed since last review - -### Pitfall 5: Not Linking to Issues - -- ❌ **Problem**: PR not connected to GitHub issue/task -- **Why it happens**: Forgetting to add "Fixes #123" -- ✅ **Solution**: Always link PRs to issues for traceability -- **Example**: Can't understand context or priority of PR - -## Edge Cases - -### Edge Case 1: Emergency Hotfix - -**When**: Production bug requires immediate fix -**Approach**: -- Create hotfix branch from main -- Minimal fix only (no refactoring) -- Fast-track review (1 approver minimum) -- Merge immediately after approval -- Create follow-up issue for proper fix -**Example**: Routing service returning 500 for all requests - -### Edge Case 2: Breaking Changes - -**When**: PR includes breaking API changes -**Approach**: -- Document all breaking changes in PR description -- Include migration guide -- Version bump (major version) -- Coordinate with dependent services -**Example**: Changing RoutingRequest schema - -### Edge Case 3: Large Refactoring - -**When**: Refactoring touches many files but preserves behavior -**Approach**: -- Break into multiple PRs if possible -- Comprehensive test coverage before starting -- Mark as "refactor:" in title -- Emphasize behavior preservation in description -**Example**: Extracting shared utilities to library - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| PR sits unreviewed for days | Too large or unclear | Break into smaller PRs, improve description | -| CI keeps failing | Not running tests locally | Run full CI suite locally before pushing | -| Review feedback unclear | Missing context | Ask clarifying questions, iterate | -| Conflicts on every push | Branch out of date | Regularly merge main into feature branch | -| Can't merge after approval | CI failed on latest commit | Fix CI, request re-approval if needed | -| PR reverted after merge | Broke production | Add integration tests, stage testing | -| Lost track of review changes | Force-pushed during review | Don't force-push, add new commits | - -## Related Instructions - -**Core Workflow**: -- [Code Review Standards](./code_review_standards.instructions.md) - Review process, feedback standards, approval criteria -- [CI/CD Pipelines](../devops/ci_cd_pipelines.instructions.md) - CI quality gates (typecheck, lint, test, build) -- [Git Safety](../safety_prevention/git_safety.instructions.md) - Safe git practices, avoiding force-push, branch management - -**Quality Requirements**: -- [Testing Standards](./testing_standards.instructions.md) - Test coverage requirements before PR -- [Test-Driven Development](../development_standards/test_driven_development.instructions.md) - Writing tests for PR changes -- [Deterministic Validation Framework](../validation/deterministic_validation_framework.instructions.md) - Validation requirements in CI - -**Integration**: -- [GitHub Integration](../github_integration/github_essentials.instructions.md) - GitHub PR workflow, branch protection -- [Database Migrations](../devops/database_migrations.instructions.md) - Including migrations in PRs, migration review checklist -- [Security Hardening](../security/security_hardening.instructions.md) - Security review in PRs - ---- - -**Success Criteria**: All PRs use template, link to issues, pass CI before review, are <400 lines, get reviewed within 24 hours, merge with squash commits. - -**Confidence Check**: Does every PR have complete description? Are all CI gates passing before review? Is PR size manageable? Are changes focused on one logical change? diff --git a/.pongogo/instructions/safety_prevention/git_safety.instructions.md b/.pongogo/instructions/safety_prevention/git_safety.instructions.md deleted file mode 100644 index 9cef3f46..00000000 --- a/.pongogo/instructions/safety_prevention/git_safety.instructions.md +++ /dev/null @@ -1,385 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Git Safety" -description: "Git safety rules to prevent data loss, destructive operations, and accidental force pushes." -applies_to: - - "**/*" -domains: - - "safety" -priority: "P1" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 1 - triggers: - keywords: - - git_safety - - destructive_git - - git_reset - - force_push - - mass_deletion - - backup_branch - - git_stash - - protected_branch - - pre-commit_hook - - content_deletion - nlp: "Preventing destructive git operations, mass content deletion, force push protection, backup creation before risky operations" -evaluation: - success_signals: - - Backup branch created before destructive operations - - git diff --stat reviewed for large deletions - - --force-with-lease used instead of --force - - Zero unintended data loss - failure_signals: - - Destructive operation without backup - - Mass deletion committed without review - - Force push without --force-with-lease - - Pre-commit hooks bypassed without documented reason ---- - - -# Git Safety Protocols - -**Purpose**: Prevent destructive git operations, mass content deletion, and data loss through systematic safeguards and validation gates. - -**Philosophy**: Data preservation over convenience - explicit confirmation required for any operation risking data loss. - ---- - -## When to Apply - -Apply these protocols when: - -- Performing any git operation that modifies history (reset, rebase, amend) -- Committing substantial content deletions (>1000 lines or >50% file content) -- Working with protected infrastructure files (workflows, templates, configs) -- Force pushing to any branch -- Cleaning working directory or removing untracked files -- Modifying pre-commit hooks or bypassing validation - ---- - -## Quick Reference - -**Most Common Safe Patterns**: - -**1. Safe Undo (Instead of Hard Reset)**: -```bash -# ❌ Dangerous: Loses uncommitted work -git reset --hard HEAD - -# ✅ Safe: Stash changes for recovery -git stash push -m "backup before cleanup" -git checkout . -``` - -**2. Backup Before Destructive Operation**: -```bash -# Always create backup branch first -git branch backup-$(date +%Y%m%d-%H%M%S) -git rebase main -``` - -**3. Detect Large Deletions**: -```bash -# Check diff stats before committing -git diff --stat -# If >1000 lines deleted, verify intentional -``` - -**4. Protected File Check**: -```bash -# Verify no accidental changes to critical files -git diff --name-only | grep -E "\.github/|docs/|\.instructions\.md" -``` - -**5. Never Force Push to Main**: -```bash -# ❌ NEVER do this -git push --force origin main - -# ✅ If really needed, use --force-with-lease -git push --force-with-lease origin feature-branch -``` - ---- - -## Core Principles - -- **Explicit Confirmation**: Never execute destructive operations without user understanding of consequences -- **Backup First**: Create backup branches before major operations -- **Safer Alternatives**: Prefer `git stash`, `git checkout` over `git reset --hard` -- **Content Deletion Detection**: Flag commits removing >1000 lines or >50% of file content -- **Protected Files**: Extra validation for critical infrastructure (`.github/`, `docs/`, instruction files) - -## Step-by-Step Guidance - -### 1. **Assess Operation Risk Level** - - Categorize as: Safe (checkout, status, log), Risky (reset, force push), Destructive (reset --hard, clean -f) - - For Risky/Destructive: Require explicit user confirmation with explanation - - For mass content deletion: Trigger content reduction assessment - - Expected outcome: Operation risk level identified - -### 2. **Content Reduction Assessment (Pre-Commit)** - - Run `git diff --stat` before any commit - - Flag commits removing >1000 lines - - Flag commits reducing file content by >50% - - Flag any instruction file, template, or workflow becoming empty - - Expected outcome: Mass deletion detected before commit - -### 3. **Protected Infrastructure Validation** - - Never empty instruction files (`.github/instructions/*.md`) without explicit rationale - - Never empty issue templates (`.github/ISSUE_TEMPLATE/*.yml`) - - Never empty workflow files (`.github/workflows/*.yml`) - - Never empty documentation (`docs/**/*.md`) without migration plan - - Expected outcome: Critical infrastructure protected from accidental deletion - -### 4. **Create Backup Before Destructive Operations** - - Create backup branch: `git branch backup-$(date +%Y%m%d-%H%M%S)` - - Verify backup exists before proceeding - - Document backup branch in work log or issue comment - - Expected outcome: Recovery path available if operation fails - -### 5. **Execute with Validation** - - Use `git show --stat HEAD~1..HEAD` to review changes after commit - - Confirm empty files are intentionally empty - - Document rationale for mass content removal in commit message - - Run CI/CD validations before push - - Expected outcome: Changes validated before becoming permanent - -### 6. **Post-Operation Verification** - - Verify expected files still exist: `ls -la key-directories/` - - Check file sizes haven't dramatically changed: `du -sh target-files` - - Run test suite to catch functional breakage - - Review git log for unintended changes - - Expected outcome: Operation completed successfully without data loss - -## Examples - -### Example 1: Safe Alternative to Destructive Reset - -Scenario: Developer wants to discard uncommitted changes - -```bash -# ❌ DANGEROUS: Destroys uncommitted work permanently -git reset --hard HEAD - -# ✅ SAFE ALTERNATIVE 1: Preserve changes in stash -git stash push -m "backup before reset $(date +%Y%m%d-%H%M%S)" -# Later can recover: git stash pop - -# ✅ SAFE ALTERNATIVE 2: Create backup branch -git branch backup-uncommitted-$(date +%Y%m%d-%H%M%S) -git add -A -git commit -m "Backup before reset" -git reset --hard HEAD~1 - -# ✅ SAFE ALTERNATIVE 3: Selective file revert -git checkout -- specific-file.ts -# Only reverts specific files, preserves others -``` - -**Context**: Stash or backup branch provides recovery path if reset was mistake -**Expected Result**: Changes preserved for potential recovery - -### Example 2: Mass Content Deletion Detection - -Scenario: Commit inadvertently empties instruction files - -```bash -# Pre-commit validation script (should be in .git/hooks/pre-commit) -#!/bin/bash - -# Get diff statistics -DIFF_STAT=$(git diff --cached --stat) - -# Check for large deletions -DELETIONS=$(echo "$DIFF_STAT" | grep -oP '\d+(?= deletion)') -if [ ! -z "$DELETIONS" ] && [ "$DELETIONS" -gt 1000 ]; then - echo "⚠️ WARNING: This commit removes $DELETIONS lines" - echo "⚠️ Large content deletion detected - please review carefully" - echo "" - echo "Files affected:" - git diff --cached --stat | grep "| .*-" - echo "" - read -p "Proceed with commit? (yes/no): " CONFIRM - if [ "$CONFIRM" != "yes" ]; then - echo "Commit aborted" - exit 1 - fi -fi - -# Check for empty instruction files -EMPTY_INSTRUCTIONS=$(git diff --cached --name-only | grep '\.instructions\.md$' | while read file; do - if [ ! -s "$file" ]; then - echo "$file" - fi -done) - -if [ ! -z "$EMPTY_INSTRUCTIONS" ]; then - echo "🚨 CRITICAL: Instruction files becoming empty:" - echo "$EMPTY_INSTRUCTIONS" - echo "" - echo "This is likely unintentional content deletion." - read -p "Type 'DELETE' to confirm intentional deletion: " CONFIRM - if [ "$CONFIRM" != "DELETE" ]; then - echo "Commit aborted" - exit 1 - fi -fi - -exit 0 -``` - -**Context**: Automated pre-commit hook prevents accidental mass deletion -**Expected Result**: User explicitly confirms large deletions, preventing mistakes - -### Example 3: Protected Branch Operations - -Scenario: Force pushing to main branch - -```bash -# ❌ DANGEROUS: Force push without protection -git push --force origin main - -# ✅ SAFE APPROACH: Protected branch workflow - -# Step 1: Verify branch protection status -gh api repos/{owner}/{repo}/branches/main/protection - -# Step 2: Create backup branch first -git branch backup-main-$(date +%Y%m%d-%H%M%S) -git push origin backup-main-$(date +%Y%m%d-%H%M%S) - -# Step 3: Use --force-with-lease (safer than --force) -git push --force-with-lease origin main -# Fails if remote changed since last fetch, preventing overwrites - -# Step 4: Verify push success -git log origin/main --oneline -n 5 - -# If force push absolutely necessary: -# 1. Document reason in work log -# 2. Notify team in advance -# 3. Create backup branch -# 4. Use --force-with-lease -# 5. Verify result immediately -``` - -**Context**: Protected branches require extra validation and backup -**Trade-offs**: --force-with-lease safer than --force, but both should be rare and documented - -## Validation Checklist - -Before executing potentially destructive git operations: - -### Risk Assessment -- [ ] Operation risk level identified (Safe/Risky/Destructive) -- [ ] User confirmation obtained for Risky/Destructive operations -- [ ] Consequences explained clearly to user -- [ ] Safer alternatives considered and rejected with rationale - -### Content Protection -- [ ] `git diff --stat` reviewed for large deletions -- [ ] No instruction files becoming empty unintentionally -- [ ] No templates or workflows being deleted accidentally -- [ ] Content reduction rationale documented in commit message - -### Backup Creation -- [ ] Backup branch created: `backup-$(date +%Y%m%d-%H%M%S)` -- [ ] Backup branch pushed to remote (for critical operations) -- [ ] Backup documented in work log or issue comment -- [ ] Recovery procedure documented - -### Post-Operation Validation -- [ ] Expected files still exist -- [ ] File sizes reasonable (not dramatically reduced) -- [ ] Test suite passes -- [ ] CI/CD validations pass -- [ ] Git log reviewed for unintended changes - -## Common Pitfalls - -### Pitfall 1: Using `git reset --hard` Without Backup - -- ❌ **Problem**: Destroys uncommitted work permanently, no recovery path -- **Why it happens**: Quick fix for "undo everything" without thinking -- ✅ **Solution**: Use `git stash` or create backup branch first -- **Example**: `git stash push -m "backup"` before any reset operation - -### Pitfall 2: Force Pushing Without `--force-with-lease` - -- ❌ **Problem**: `--force` overwrites remote changes made by others -- **Why it happens**: Unaware of safer alternative -- ✅ **Solution**: Always use `--force-with-lease` which fails if remote changed -- **Example**: `git push --force-with-lease origin feature-branch` - -### Pitfall 3: Bypassing Pre-Commit Hooks - -- ❌ **Problem**: Using `--no-verify` to skip validation, committing problematic code -- **Why it happens**: Impatience or not understanding why hook failed -- ✅ **Solution**: Fix the actual issue causing hook failure -- **Example**: Fix ESLint errors instead of bypassing with `--no-verify` - -### Pitfall 4: Mass Content Deletion Without Review - -- ❌ **Problem**: Committing large deletions without verifying intentionality -- **Why it happens**: Not reviewing `git diff` before committing -- ✅ **Solution**: Always run `git diff --stat` and review substantial deletions -- **Example**: Notice instruction file went from 500 lines → 0 lines, investigate before committing - -## Edge Cases - -### Edge Case 1: Emergency Rollback Required - -**When**: Production issue requires immediate revert, normal process too slow -**Approach**: -- Create backup branch even in emergency: `git branch emergency-backup-$(date +%Y%m%d-%H%M%S)` -- Document emergency action in incident log -- Use `git revert` instead of `git reset` when possible (preserves history) -- Follow up with proper fix after incident resolved -**Example**: `git revert HEAD --no-edit && git push origin main` (safer than reset) - -### Edge Case 2: Pre-Commit Hook False Positive - -**When**: Legitimate change flagged as problematic by pre-commit hook -**Approach**: -- Investigate why hook flagged the change -- Verify change is actually safe -- Document rationale for override -- Use `--no-verify` only if absolutely necessary -- Report false positive to improve hook logic -**Example**: Large legitimate refactor flagged as mass deletion - document in commit message - -### Edge Case 3: Corrupted Repository State - -**When**: Repository in inconsistent state, normal git operations failing -**Approach**: -- Backup entire repository directory: `cp -r .git .git.backup` -- Try `git fsck` to identify corruption -- Attempt recovery with `git reflog` -- If unfixable, clone fresh and copy working directory changes -**Example**: `git clone fresh-repo && cp -r old-repo/src fresh-repo/src` - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| Lost uncommitted work after reset | `git reset --hard` without backup | Check `git reflog`, may be recoverable; create stash/backup in future | -| Force push rejected | Remote changed since last fetch | Use `git pull --rebase` then `git push --force-with-lease` | -| Pre-commit hook failing | Code doesn't meet quality standards | Fix the actual issue (ESLint, Prettier, secrets detection) | -| Large deletion committed accidentally | No pre-commit validation | Revert commit immediately: `git revert HEAD` | -| Cannot push to protected branch | Branch protection rules active | Use PR workflow or request temporary protection disable with rationale | - -## Related Instructions - -- **See also**: [systematic_prevention_framework.instructions.md](./systematic_prevention_framework.instructions.md) - Broader prevention patterns git safety implements -- **Integration**: [validation_first_execution.instructions.md](./validation_first_execution.instructions.md) - Validation before destructive operations -- **Prerequisites**: [deterministic_validation_framework.instructions.md](../validation/deterministic_validation_framework.instructions.md) - 100% pass rate for safety validations - ---- - -**Success Criteria**: Zero unintended data loss through git operations, all destructive operations require explicit confirmation with backup creation, mass content deletions detected and validated before commit. - -**Confidence Check**: Is backup branch created before destructive operations? Is `git diff --stat` reviewed for large deletions? Are protected files (instructions, templates, workflows) safeguarded? Is `--force-with-lease` used instead of `--force`? diff --git a/.pongogo/instructions/safety_prevention/systematic_prevention_framework.instructions.md b/.pongogo/instructions/safety_prevention/systematic_prevention_framework.instructions.md deleted file mode 100644 index de4c74e0..00000000 --- a/.pongogo/instructions/safety_prevention/systematic_prevention_framework.instructions.md +++ /dev/null @@ -1,419 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Systematic Prevention Framework" -description: "Systematic framework for preventing recurring failures through pattern recognition." -applies_to: - - "**/*" -domains: - - "safety" -priority: "P1" -pongogo_version: "2026-02-12" -source: "Original" - -evaluation: - success_signals: - - Every problem triggers prevention analysis before solving - - Solution eliminates problem category (not just instance) - - Prevention framework activates automatically without manual memory - - Friction signals trigger PAUSE and prevention question analysis - - Root cause addressed (not surface symptoms) - failure_signals: - - Fixing specific bug without asking what category it represents - - Creating manual processes that rely on remembering to check - - Point solution solves this instance but problem recurs - - Prevention framework requires manual activation or consultation - - Building new tools when decision pattern should be documented ---- - - -# Systematic Prevention Framework - -**Purpose**: Eliminate entire categories of problems through systematic frameworks rather than solving individual problem instances. - -**Philosophy**: Never just solve problems—always create prevention mechanisms that make entire categories of problems impossible through proper protocols and agent-first design. - ---- - -## When to Apply - -Use systematic prevention framework when: - -- Encountering any problem or error (ask "is this a pattern?") -- Creating solutions to specific issues -- Designing new features or systems -- Reviewing incidents or failures -- Building agent workflows and routing logic -- Creating instruction files or documentation - ---- - -## Quick Reference - -**Key Decision Criteria**: - -**1. Systematic Prevention Questions (Ask Every Time)**: -- Is this a one-time issue or a pattern? -- Can we prevent this entire category of problems? -- What framework would make this impossible? -- Does a prevention mechanism already exist? - -**2. Prevention vs Reaction**: -- ❌ Reaction: Fix this specific bug -- ✅ Prevention: Add validation framework preventing this bug class - -**3. Examples of Category Elimination**: -- **Problem**: Flaky tests fail randomly -- **Prevention**: Deterministic validation framework (100% pass rate requirement) -- **Problem**: Agents forget manual steps -- **Prevention**: Automatic discovery through metadata (zero memory dependency) -- **Problem**: Destructive git operations -- **Prevention**: Git safety protocols with explicit confirmation - -**4. Mandatory Analysis Before Solving**: -``` -Before: "Fix failing test" -After: "Why is test flaky? Add framework preventing non-deterministic tests" - -Before: "Update documentation" -After: "Why was documentation unclear? Add instruction file with machine-readable patterns" -``` - -**5. Integration into Workflow**: -- Prevention becomes automatic (not manual checklist) -- Runs as part of existing process (not separate step) -- Fails loudly when violated (not warning) - ---- - -## Core Principles - -- **Category Elimination**: Prevent problem categories, not individual instances -- **Mandatory Prevention Analysis**: Before solving any problem, identify what framework could eliminate the category -- **Agent-First Design**: Prevention frameworks must work automatically without manual memory -- **Root Cause Focus**: Address underlying causes creating problems, not surface symptoms -- **Process Integration**: Prevention becomes part of standard workflows, not bolt-on safeguards - -## Step-by-Step Guidance - -### 1. **Identify Problem Pattern** - - Analyze current problem: What specifically went wrong? - - Pattern recognition: Is this a one-time issue or representative of a category? - - Scope assessment: How many similar problems could exist? - - **Friction signal check**: Did this trigger user friction? (See below) - - Expected outcome: Understanding whether this is instance or pattern - -### 2. **Ask Mandatory Prevention Questions** - - Question 1: Is this a one-time issue or representative of a pattern? - - Question 2: What systematic framework could eliminate this entire problem category? - - Question 3: How can we make the correct approach the automatic approach? - - Expected outcome: Clear vision of prevention framework needed - -### 3. **Design Prevention Framework** - - Root cause analysis: What system gap allowed this problem to occur? - - Framework scope: What category of problems does this prevent? - - Automatic enforcement: How will framework activate without manual triggers? - - Agent-first integration: How do agents discover and apply this framework? - - Expected outcome: Complete prevention framework design - -### 4. **Implement Agent-First Prevention** - - Create instruction files with `applies_to` patterns for automatic discovery - - Integrate with existing tools (routing service, validation gates, etc.) - - Design context-aware activation based on work patterns - - Ensure zero manual dependency (works without agents remembering) - - Expected outcome: Prevention framework discoverable and automatic - -### 5. **Validate Framework Effectiveness** - - Test with scenarios beyond original problem instance - - Verify automatic discovery and application - - Confirm prevention of problem category, not just original instance - - Document framework in institutional knowledge system - - Expected outcome: Validated framework preventing problem category - -## Examples - -### Example 1: Routing Service Instruction Discovery - -Context: Agent failed to consult relevant instructions during feature implementation - -```markdown -## ❌ WRONG: Point Solution -Problem: Agent didn't read security_patterns.instructions.md during auth implementation -Solution: "Remember to check instruction files before implementing features" - -Why Wrong: -- Solves individual instance (this one agent, this one feature) -- Relies on agent memory (manual process) -- Doesn't prevent category (agents will forget again) - -## ✅ CORRECT: Systematic Prevention Framework -Problem Category: Agents not consulting relevant instructions during work -Root Cause: No automatic instruction discovery based on work context - -Prevention Framework: Knowledge Routing System -- Automatic Discovery: Routing service matches file paths to `applies_to` patterns -- Context-Aware Activation: Current file/domain triggers relevant instructions -- Agent-First Integration: Instructions loaded automatically when context matches -- Zero Memory Dependency: Works without agents remembering to consult - -Implementation: -1. Create routing service scanning file paths against instruction metadata -2. Load relevant instructions when agent works in matching contexts -3. Integrate with MCP server for automatic activation -4. Document in knowledge_routing_design.md architecture - -Result: -- Problem category eliminated: Agents always have relevant instructions -- Automatic enforcement: No manual consultation required -- Institutional knowledge: Routing patterns preserved in architecture -``` - -**Context**: Agent-first design requires automatic instruction discovery -**Expected Result**: Entire category of "missed instruction" problems eliminated through routing service - -### Example 2: Validation Framework Pattern - -Context: Test failed because environment variable missing, agent didn't catch during development - -```markdown -## ❌ WRONG: Point Solution -Problem: Missing DATABASE_URL environment variable caused test failure -Solution: "Add DATABASE_URL to .env file" - -Why Wrong: -- Solves this one variable, not category -- Doesn't prevent next missing variable -- Reactive (catches after failure, not before) - -## ✅ CORRECT: Systematic Prevention Framework -Problem Category: Missing required environment variables causing runtime failures -Root Cause: No validation of environment configuration at service startup - -Prevention Framework: Environment Validation at Startup -- Validation-First Pattern: Every service validates env vars before operations -- Explicit Requirements: env_requirements.yml defines required variables per service -- Fail-Fast Design: Service refuses to start if required vars missing -- Clear Error Messages: Tells developer exactly which vars needed - -Implementation: -1. Create agent_environment_setup.instructions.md with validation pattern -2. Add startup validation to microservices_development.instructions.md -3. Create env_requirements.yml schema for each service -4. Integrate validation into Docker container entrypoint scripts - -Result: -- Problem category eliminated: Missing env vars caught at startup, not runtime -- Developer experience: Clear error messages guide configuration -- Institutional pattern: All future services follow validation pattern -``` - -**Context**: Microservices architecture needs environment validation -**Expected Result**: All missing environment variable problems prevented at startup - -### Example 3: Trust-Based Execution Framework - -Context: Agent re-analyzed completed phase instead of implementing recommendations - -```markdown -## ❌ WRONG: Point Solution -Problem: Agent questioned initial analysis and re-did work during implementation -Solution: "Trust the previous analysis and implement as specified" - -Why Wrong: -- Solves this one instance of distrust -- Doesn't prevent pattern of re-analysis -- Manual guidance, not systematic framework - -## ✅ CORRECT: Systematic Prevention Framework -Problem Category: Agents re-analyzing completed work instead of trusting validation -Root Cause: No clear trust protocol for phase boundaries and validation gates - -Prevention Framework: Trust-Based Phase Execution with SC/AC/CV Gates -- Trust Foundation: SC/AC/CV validation gates establish trust during work -- Linear Progression: Each phase trusts previous phase outputs -- Cross-Session Trust: Trust extends across sessions via verification efficiency -- Meta-System Learning: Improve future criteria, don't question past completion - -Implementation: -1. Create trust_based_task_execution.instructions.md (P0 priority) -2. Document SC/AC/CV gates in feature_development.instructions.md -3. Integrate with verification_efficiency.instructions.md for cross-session trust -4. Make trust-based execution universal pattern (`applies_to: "**/*"`) - -Result: -- Problem category eliminated: Agents trust completed phases systematically -- Efficiency gains: No re-analysis waste, linear time complexity -- Learning culture: Improvements feed forward, not backward-looking doubt -``` - -**Context**: Multi-phase feature team coordination requires trust framework -**Expected Result**: Re-analysis anti-pattern eliminated through systematic trust protocols - -## Validation Checklist - -Before implementing any solution: - -- [ ] Problem pattern identified (instance vs category) -- [ ] Mandatory prevention questions answered -- [ ] Root cause analysis completed (not just symptoms) -- [ ] Prevention framework designed (eliminates category) -- [ ] Agent-first integration planned (automatic discovery) -- [ ] Process integration defined (part of standard workflow) -- [ ] Validation scenarios beyond original problem defined -- [ ] Institutional knowledge documentation planned - -After implementing prevention framework: - -- [ ] Framework prevents problem category, not just instance -- [ ] Automatic activation verified (no manual memory required) -- [ ] Works with existing tools (no new tool dependencies) -- [ ] Instruction files created with proper `applies_to` patterns -- [ ] Cross-referenced in related instruction files -- [ ] Tested with scenarios beyond original problem -- [ ] Documented in architecture and knowledge system - -## Common Pitfalls - -### Pitfall 1: Solving Individual Problems Without Prevention Analysis - -- ❌ **Problem**: Fixing specific bug without asking "what category does this represent?" -- **Why it happens**: Action bias, pressure to solve quickly -- ✅ **Solution**: Mandatory pause before fixing, ask prevention questions first -- **Example**: Fix this auth bug → Ask "what authentication framework prevents this category?" - -### Pitfall 2: Creating Manual Processes Instead of Systematic Frameworks - -- ❌ **Problem**: "Remember to check X before doing Y" (relies on memory) -- **Why it happens**: Treating humans/agents as responsible for remembering -- ✅ **Solution**: Design automatic discovery and enforcement, not manual checklists -- **Example**: "Remember to consult instructions" → Build routing service for automatic instruction loading - -### Pitfall 3: Building Tools Instead of Documenting Patterns - -- ❌ **Problem**: Creating new scripts/tools when decision pattern should be documented -- **Why it happens**: Tool-first thinking instead of knowledge-first approach -- ✅ **Solution**: Document decision frameworks in instruction files, leverage existing tools -- **Example**: Build custom analyzer → Document analysis patterns in instructions for agent inference - -### Pitfall 4: Preventing Symptoms Instead of Root Causes - -- ❌ **Problem**: Adding validation layers that catch problems after they occur -- **Why it happens**: Reactive instead of proactive prevention design -- ✅ **Solution**: Eliminate root cause so problem category cannot occur -- **Example**: Validate env vars after startup failure → Validate at startup so service won't run without vars - -### Pitfall 5: Prevention Without Agent-First Design - -- ❌ **Problem**: Prevention framework requires manual activation or consultation -- **Why it happens**: Not considering agent discovery and automation -- ✅ **Solution**: Integrate with routing service, use `applies_to` patterns, automatic triggers -- **Example**: Manual instruction lookup → Automatic instruction routing based on context patterns - -## Friction Signals as Prevention Triggers (Routing IMP-018) - -**Principle**: Friction signals are real-time evidence that a problem category needs prevention. - -### Friction Detection Patterns - -When users express these signals, a systematic gap has been exposed: - -| Friction Signal | What It Reveals | Prevention Question | -|-----------------|-----------------|---------------------| -| "yet another example of" | Recurring issue (pattern!) | What framework prevents this category? | -| "i thought we changed this" | Expectation not met | Why did expectation differ from reality? | -| "without going through process" | Process being bypassed | How to make process automatic, not optional? | -| "you're skipping" | Steps being missed | What gate ensures step cannot be skipped? | -| "we already discussed this" | Previous guidance lost | How to capture guidance for automatic routing? | - -### Friction → Prevention Workflow - -1. **Detect friction signal** → PAUSE current work -2. **Ask prevention questions**: - - Is this a one-time issue or pattern? - - What category does this represent? - - What framework prevents this category? -3. **Capture learning** → Document for mini-retro -4. **Design prevention** → If pattern, create framework -5. **Resume work** → With corrected approach - -### Why Friction Signals Matter for Prevention - -- **Real-time evidence**: User friction = confirmed gap in current systems -- **84% correlation**: Friction signals (correction_signal type) indicate preventable issues -- **Two benefits**: (1) Fix immediate issue, (2) Prevent future category -- **Learning source**: Each friction event should feed into meta-system improvement - -### Example: Friction → Prevention - -```markdown -## Friction Event -User: "yet another example of not checking the wiki first" - -## Prevention Analysis -1. Pattern identified: Agents not checking wiki before decisions -2. Category: Information source consultation gaps -3. Root cause: No automatic wiki routing based on decision context - -## Prevention Framework -- Add wiki pages to routing triggers based on decision domains -- Create instruction: "wiki_consultation.instructions.md" -- Automatic activation: Decision keywords → wiki pages surface - -## Result -Category prevented: Future decisions in same domain automatically get wiki context -``` - -## Edge Cases - -### Edge Case 1: True One-Time Issues (Not Patterns) - -**When**: Problem genuinely is one-time with no recurrence likelihood -**Approach**: -- Still ask prevention questions to confirm it's truly one-time -- Document decision: "Confirmed one-time because..." -- Solve efficiently without framework overhead -- Monitor: If recurs, upgrade to prevention framework -**Example**: Corrupted file from disk failure → Fix file, confirm hardware issue, monitor for pattern - -### Edge Case 2: Prevention Framework Too Complex for Value - -**When**: Building prevention framework costs more than accepting occasional instance -**Approach**: -- Document cost-benefit analysis explicitly -- Create lightweight guidance instead of automated enforcement -- Set recurrence threshold for upgrading to full framework -- Preserve decision rationale in documentation -**Example**: Rare edge case occurring <1x/year → Document handling in troubleshooting section, not full automation - -### Edge Case 3: Conflicting Prevention Frameworks - -**When**: Two prevention frameworks interfere with each other -**Approach**: -- Identify conflict root cause (usually scope overlap) -- Redesign frameworks to be complementary, not contradictory -- Use priority levels (P0 > P1 > P2) when conflict unavoidable -- Document precedence rules in both framework instruction files -**Example**: Safety framework requires validation, speed framework skips checks → Define when each applies - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| Same problem recurring | Point solution instead of prevention framework | Analyze problem category, design framework eliminating root cause | -| Prevention framework not applied | Agent-first design missing | Add `applies_to` patterns, integrate with routing service | -| Agents bypass prevention | Manual activation required | Make automatic through context-aware triggers | -| Prevention too complex | Over-engineered solution | Simplify to essential pattern, leverage existing tools | -| Framework conflicts with workflow | Bolt-on instead of integration | Redesign as part of standard workflow | -| Prevention doesn't scale | Instance-specific solution | Generalize to category-level framework | - -## Related Instructions - -- **See also**: [agentic_decision_making.instructions.md](../agentic_workflows/agentic_decision_making.instructions.md) - Inference patterns support systematic prevention over point solutions -- **Prerequisites**: [validation_first_execution.instructions.md](./validation_first_execution.instructions.md) - Validation-first is specific application of systematic prevention -- **Integration**: [instruction_file_creation.instructions.md](../documentation/instruction_file_creation.instructions.md) - Prevention frameworks documented in instruction files for agent discovery -- **Example**: [trust_based_task_execution.instructions.md](../trust_execution/trust_based_task_execution.instructions.md) - Trust framework eliminates re-analysis problem category - ---- - -**Success Criteria**: Every problem triggers prevention analysis. Solutions eliminate problem categories through agent-first frameworks integrated into standard workflows. No recurring problems that could be systematically prevented. - -**Confidence Check**: Are you solving this specific instance or eliminating the problem category? Will this framework work automatically without agents remembering it exists? Have you asked the three mandatory prevention questions? diff --git a/.pongogo/instructions/safety_prevention/validation_first_execution.instructions.md b/.pongogo/instructions/safety_prevention/validation_first_execution.instructions.md deleted file mode 100644 index f1ebfc00..00000000 --- a/.pongogo/instructions/safety_prevention/validation_first_execution.instructions.md +++ /dev/null @@ -1,554 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Validation-First Execution" -description: "Validate before executing to prevent destructive actions and data loss." -applies_to: - - "**/*" -domains: - - "safety" -priority: "P1" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 0 - triggers: - keywords: - - dry_run - - validation_first - - validate_before - - debug_flag - - verbose_flag - - help_flag - - script_safety - - bulk_operation - - migration_script - - deployment_script - nlp: "Validation-first execution with dry-run, debug, verbose flags for scripts and operations, systematic prevention before execution" -evaluation: - success_signals: - - Script supports --help, --dry-run, --debug, --verbose flags - - Dry-run executed before first real execution of any script - - Current state queried before making modifications (targeted changes) - - Debug output shows variable values and decision points - - Post-execution validation confirms intended changes occurred - failure_signals: - - Script executes immediately without dry-run validation option - - Dry-run shows all items as targets (not checking current state) - - First execution skips dry-run due to confidence or time pressure - - Debug flag enabled but doesn't show decision logic - - No --help documentation for script flags and usage ---- - - -# Validation-First Execution - -**Purpose**: Establish systematic prevention pattern where all scripts and operations validate before executing to eliminate entire categories of errors. - -**Philosophy**: Validate first, execute second - see what will happen before making it happen. - ---- - -## When to Apply - -Use validation-first execution when: - -- Creating any script that modifies state (files, database, API calls) -- Running bulk operations affecting multiple items -- Executing deployment or migration scripts -- Making configuration changes -- Running operations for the first time -- Working with production data or systems - ---- - -## Quick Reference - -**Most Common Patterns**: - -**1. Bash Script with Dry-Run**: -```bash -#!/bin/bash -DRY_RUN=false -while [[ $# -gt 0 ]]; do - case $1 in - -d|--dry-run) DRY_RUN=true; shift ;; - *) shift ;; - esac -done - -if [ "$DRY_RUN" = true ]; then - echo "[DRY-RUN] Would delete: $file" -else - rm "$file" -fi -``` - -**2. Python Script with argparse**: -```python -import argparse -parser = argparse.ArgumentParser() -parser.add_argument('--dry-run', action='store_true') -parser.add_argument('--debug', action='store_true') -args = parser.parse_args() - -if args.dry_run: - print(f"[DRY-RUN] Would update: {item}") -else: - update_item(item) -``` - -**3. Always Run Dry-Run First**: -```bash -# First: See what will happen -./script.sh --dry-run - -# Review output, then execute -./script.sh -``` - -**4. Debug Flag for Visibility**: -```python -if args.debug: - print(f"DEBUG: Current state = {state}") - print(f"DEBUG: Applying change = {change}") -``` - ---- - -## Core Principles - -- **Dry-Run by Default**: Every script should support `--dry-run` to show what would happen without executing -- **Debug Visibility**: Use `--debug` flag to show detailed execution flow and decision points -- **Verbose Logging**: Implement `--verbose` for different levels of output detail -- **Help Always Available**: Every script must have `--help` documenting all flags and usage -- **Verify Current State**: Check existing state before making changes to understand impact - -## Step-by-Step Guidance - -### 1. **Implement Standard Safety Flags** - - Add `--dry-run` (or `-d`): Show what would be done without making changes - - Add `--debug`: Display detailed execution flow, variable values, decision logic - - Add `--verbose` (or `-v`): Control log level (warnings, info, debug) - - Add `--help` (or `-h`): Display usage, examples, and flag documentation - - Expected outcome: Script supports all four safety flags - -### 2. **Always Run Dry-Run First** - - Execute script with `--dry-run` before real execution - - Review proposed changes for correctness - - Validate scope matches intention (no accidental bulk operations) - - Expected outcome: Confident understanding of what will happen - -### 3. **Verify Current State** - - Query existing state before making modifications - - Check if target items are already in desired state - - Identify which items need changes vs which are already correct - - Expected outcome: Targeted changes only, no unnecessary modifications - -### 4. **Enable Debug for First-Time Execution** - - Use `--debug` flag when running script for first time - - Observe decision points and data flow - - Verify logic behaves as expected - - Expected outcome: Increased confidence through visibility - -### 5. **Execute with Verbose Logging** - - Run actual execution with `--verbose` for progress tracking - - Monitor for unexpected behavior - - Capture log output for post-execution review - - Expected outcome: Complete audit trail of what happened - -### 6. **Validate Post-Execution** - - Check that intended changes occurred - - Verify no unintended side effects - - Confirm system state matches expectations - - Expected outcome: Confirmed success or identified issues requiring correction - -## Examples - -### Example 1: Bash Script with Standard Safety Flags - -Script implementing all four safety flags: - -```bash -#!/bin/bash -# migrate-instructions.sh - Migrate instruction files to new structure - -set -euo pipefail - -# Default values -DRY_RUN=false -DEBUG=false -VERBOSE=false - -show_help() { - cat << EOF -Usage: $(basename "$0") [OPTIONS] - -Migrate instruction files from old structure to new structure. - -Options: - -d, --dry-run Show what would be done without making changes - -v, --verbose Enable verbose logging - --debug Enable debug mode (show all variable values and decisions) - -h, --help Show this help message - -Examples: - # See what would happen first - $(basename "$0") --dry-run - - # Run with verbose output - $(basename "$0") --verbose - - # Debug first-time execution - $(basename "$0") --debug --dry-run - -EOF -} - -log_info() { - if [[ "$VERBOSE" == "true" ]]; then - echo "[INFO] $*" - fi -} - -log_debug() { - if [[ "$DEBUG" == "true" ]]; then - echo "[DEBUG] $*" - fi -} - -migrate_file() { - local source="$1" - local target="$2" - - log_debug "migrate_file called with source=$source, target=$target" - - # Verify current state - if [[ -f "$target" ]]; then - log_info "Target already exists: $target (skipping)" - return 0 - fi - - if [[ "$DRY_RUN" == "true" ]]; then - echo "[DRY-RUN] Would migrate: $source -> $target" - else - log_info "Migrating: $source -> $target" - cp "$source" "$target" - log_debug "Migration complete: $target" - fi -} - -# Parse arguments -while [[ $# -gt 0 ]]; do - case $1 in - -d|--dry-run) - DRY_RUN=true - echo "[DRY-RUN MODE] No changes will be made" - shift - ;; - -v|--verbose) - VERBOSE=true - shift - ;; - --debug) - DEBUG=true - VERBOSE=true # Debug implies verbose - echo "[DEBUG MODE] Detailed execution logging enabled" - shift - ;; - -h|--help) - show_help - exit 0 - ;; - *) - echo "Error: Unknown option $1" - show_help - exit 1 - ;; - esac -done - -# Main execution -log_debug "Starting migration with DRY_RUN=$DRY_RUN, VERBOSE=$VERBOSE, DEBUG=$DEBUG" - -# Your script logic here -migrate_file "old/path/file.md" "new/path/file.md" - -if [[ "$DRY_RUN" == "true" ]]; then - echo "[DRY-RUN] Dry-run complete. No changes were made." - echo "[DRY-RUN] Run without --dry-run to apply changes." -fi -``` - -**Context**: Standard template for bash scripts requiring safety validation -**Expected Result**: Safe execution with visibility and validation - -### Example 2: Python Script with Safety Flags - -Python script implementing validation-first pattern: - -```python -#!/usr/bin/env python3 -""" -update-frontmatter.py - Update YAML frontmatter in instruction files - -Implements validation-first execution with dry-run, debug, and verbose flags. -""" - -import argparse -import logging -import sys -from pathlib import Path - -def setup_logging(verbose: bool, debug: bool): - """Configure logging based on flags""" - if debug: - level = logging.DEBUG - elif verbose: - level = logging.INFO - else: - level = logging.WARNING - - logging.basicConfig( - level=level, - format='[%(levelname)s] %(message)s' - ) - -def update_frontmatter(file_path: Path, new_field: str, dry_run: bool) -> bool: - """ - Update frontmatter in instruction file. - - Args: - file_path: Path to instruction file - new_field: New field to add - dry_run: If True, only show what would happen - - Returns: - True if update needed, False if already up-to-date - """ - logging.debug(f"update_frontmatter called: file={file_path}, field={new_field}, dry_run={dry_run}") - - # Verify current state - content = file_path.read_text() - if new_field in content: - logging.info(f"Skipping {file_path} - already has {new_field}") - return False - - if dry_run: - print(f"[DRY-RUN] Would add '{new_field}' to {file_path}") - return True - - # Actual modification - logging.info(f"Adding '{new_field}' to {file_path}") - # ... update logic here ... - logging.debug(f"Update complete: {file_path}") - return True - -def main(): - parser = argparse.ArgumentParser( - description='Update YAML frontmatter in instruction files', - formatter_class=argparse.RawDescriptionHelpFormatter, - epilog=''' -Examples: - # See what would happen (always run this first) - %(prog)s --dry-run - - # Run with verbose output - %(prog)s --verbose - - # Debug first execution - %(prog)s --debug --dry-run - - # Apply changes - %(prog)s - ''' - ) - - parser.add_argument('-d', '--dry-run', action='store_true', - help='Show what would be done without making changes') - parser.add_argument('-v', '--verbose', action='store_true', - help='Enable verbose logging') - parser.add_argument('--debug', action='store_true', - help='Enable debug mode (implies verbose)') - - args = parser.parse_args() - - setup_logging(args.verbose, args.debug) - - if args.dry_run: - print("[DRY-RUN MODE] No changes will be made\n") - - logging.debug(f"Arguments: {args}") - - # Main logic - files_modified = 0 - for file_path in Path('knowledge/instructions').rglob('*.instructions.md'): - if update_frontmatter(file_path, 'new_field', args.dry_run): - files_modified += 1 - - if args.dry_run: - print(f"\n[DRY-RUN] Would modify {files_modified} files") - print("[DRY-RUN] Run without --dry-run to apply changes") - else: - logging.info(f"Modified {files_modified} files") - -if __name__ == '__main__': - main() -``` - -**Context**: Standard template for Python scripts requiring safety validation -**Expected Result**: Safe execution with validation and visibility - -### Example 3: Bulk Operation Safety - -Validating before bulk GitHub operation: - -```bash -#!/bin/bash -# bulk-update-issues.sh - Update multiple issues with safety validation - -# 1. Query current state FIRST -echo "Checking current issue status..." -for issue_num in 45 46 47 48 49; do - current_status=$(gh issue view "$issue_num" --json status -q '.status') - echo "Issue #$issue_num: current status = $current_status" - - # Save to file for dry-run analysis - echo "$issue_num:$current_status" >> /tmp/current_status.txt -done - -# 2. Dry-run showing proposed changes -if [[ "$DRY_RUN" == "true" ]]; then - echo "" - echo "[DRY-RUN] Proposed changes:" - while IFS=: read -r issue current; do - if [[ "$current" != "BACKLOG" ]]; then - echo "[DRY-RUN] Would update #$issue: $current -> BACKLOG" - else - echo "[DRY-RUN] Skipping #$issue: already in BACKLOG" - fi - done < /tmp/current_status.txt - - echo "" - echo "[DRY-RUN] Dry-run complete. Review proposed changes above." - exit 0 -fi - -# 3. Actual execution (only runs if not dry-run) -while IFS=: read -r issue current; do - if [[ "$current" != "BACKLOG" ]]; then - echo "Updating #$issue: $current -> BACKLOG" - gh issue edit "$issue" --add-project "{project}" --project-field "Status=Backlog" - else - echo "Skipping #$issue: already in BACKLOG" - fi -done < /tmp/current_status.txt -``` - -**Context**: Bulk operations require current state verification to avoid accidental changes -**Expected Result**: Targeted changes only, no disruption of correctly-positioned items - -## Validation Checklist - -Before considering a script complete: - -- [ ] `--help` flag implemented with usage examples -- [ ] `--dry-run` flag shows proposed changes without executing -- [ ] `--debug` flag displays detailed execution flow -- [ ] `--verbose` flag enables progress logging -- [ ] Script checks current state before making changes -- [ ] Dry-run output is clear and actionable -- [ ] Debug output shows variable values and decision points -- [ ] Script skips items already in desired state -- [ ] Post-execution validation confirms success -- [ ] Error handling provides recovery guidance - -## Common Pitfalls - -### Pitfall 1: No Dry-Run Flag - -- ❌ **Problem**: Script executes immediately without validation opportunity -- **Why it happens**: Treating dry-run as optional instead of mandatory -- ✅ **Solution**: Always implement `--dry-run` flag, document in `--help` -- **Example**: Script that modifies 100 files without showing what it will do first - -### Pitfall 2: Dry-Run Not Checking Current State - -- ❌ **Problem**: Dry-run shows all items as targets, not just items needing changes -- **Why it happens**: Not querying current state before proposing changes -- ✅ **Solution**: Check existing state, only show items that need modification -- **Example**: "Would update 50 issues" when 45 are already in correct state - -### Pitfall 3: Debug Output Missing Key Information - -- ❌ **Problem**: Debug flag enabled but doesn't show decision logic -- **Why it happens**: Not logging variable values and conditional branches -- ✅ **Solution**: Log all decisions, variable states, and control flow -- **Example**: Script fails but debug output doesn't show which condition triggered failure - -### Pitfall 4: Executing First-Time Without Dry-Run - -- ❌ **Problem**: Running script in production without seeing what it will do -- **Why it happens**: Skipping validation step due to confidence or time pressure -- ✅ **Solution**: Make dry-run mandatory for first execution (block without flag) -- **Example**: Migration script that moves 1000 files unexpectedly - -### Pitfall 5: No Help Documentation - -- ❌ **Problem**: Script flags not documented, users don't know how to validate safely -- **Why it happens**: Treating documentation as optional -- ✅ **Solution**: Comprehensive `--help` with examples of safe usage -- **Example**: Script with `--dry-run` but users don't know it exists - -## Edge Cases - -### Edge Case 1: Dry-Run for Idempotent Operations - -**When**: Operation can be safely run multiple times (already idempotent) -**Approach**: -- Still implement `--dry-run` to show scope of operation -- Use dry-run to confirm no unexpected side effects -- Document idempotency in help text -**Example**: Script that updates config only if value differs - -### Edge Case 2: Debug Output Too Verbose - -**When**: Debug flag produces overwhelming amount of output -**Approach**: -- Implement multiple verbosity levels (`-v`, `-vv`, `-vvv`) -- Default debug to showing decisions, use `-vv` for data dumps -- Provide `--debug-file` to write debug output to file instead of stdout -**Example**: Script processing 10,000 items needs tiered debug levels - -### Edge Case 3: Dry-Run Cannot Fully Simulate - -**When**: Operation depends on external API responses or runtime conditions -**Approach**: -- Document limitations in dry-run output -- Show best-effort simulation with warnings -- Recommend starting with small subset (add `--limit` flag) -**Example**: API migrations where response format can't be predicted - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| Script runs without validation | No `--dry-run` flag implemented | Add dry-run flag, block execution without it for first run | -| Dry-run shows too many targets | Not checking current state | Query existing state, filter to items needing changes | -| Debug output unhelpful | Not logging decision points | Add logging at every conditional, log variable values | -| Can't understand what script does | No `--help` documentation | Write comprehensive help with examples | -| Unexpected bulk changes | Skipped dry-run validation | Mandate dry-run for first execution (exit with warning if skipped) | -| Script modifies wrong items | Incorrect scope validation | Add safeguards checking item IDs/patterns before changes | - -## Related Instructions - -- **See also**: [bash_script_maintenance.instructions.md](../scripting/bash_script_maintenance.instructions.md) - Comprehensive bash scripting standards including flag implementation -- **See also**: [python_script_development.instructions.md](../scripting/python_script_development.instructions.md) - Python scripting standards with argparse patterns -- **Prerequisites**: [agentic_decision_making.instructions.md](../agentic_workflows/agentic_decision_making.instructions.md) - Context-first thinking applies to validation-first execution -- **Related**: [bulk_operation_safety.instructions.md](./bulk_operation_safety.instructions.md) - Specific patterns for bulk operations - ---- - -**Success Criteria**: All scripts support `--help`, `--dry-run`, `--debug`, and `--verbose` flags. First-time execution always uses dry-run. Current state verified before modifications. - -**Confidence Check**: Can you run any script with `--help` and `--dry-run` to understand what it does before executing? Does debug output show decision logic? diff --git a/.pongogo/instructions/software_engineering/commit_message_format.instructions.md b/.pongogo/instructions/software_engineering/commit_message_format.instructions.md deleted file mode 100644 index 09cdc251..00000000 --- a/.pongogo/instructions/software_engineering/commit_message_format.instructions.md +++ /dev/null @@ -1,416 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Commit Message Format Standards" -description: "Commit message formatting standards and conventions for consistent history." -applies_to: - - "**/*" -domains: - - "software_engineering" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 1 - triggers: - keywords: - - commit_message - - commit_format - - git_commit - - model_attribution - - Co-Authored-By - - archaeological - - context-rich_commit - - What_Changed - - Why_section - - imperative_mood - nlp: "Creating context-rich commit messages with model attribution and archaeological value for future decision understanding" -evaluation: - success_signals: - - Summary line 50-72 chars in imperative mood - - What Changed and Why sections present with specifics - - Model attribution and Co-Authored-By footer included - - Archaeological value preserved (future self can understand) - failure_signals: - - Vague summary like "update files" or "fix bug" - - Missing Why section (rationale not documented) - - Missing model attribution footer - - Placeholder text in commit message ---- - - -# Commit Message Format Standards - -**Purpose**: Create commit messages that provide comprehensive context for future archaeology - understanding not just what changed, but why, how, and who (including which AI model) contributed. - -**Philosophy**: Commit messages are archaeological artifacts. Future developers (including you) will need to understand decisions, not just changes. - -**Core Problem Solved**: "Why was this change made?" "What was the context?" "Which model worked on this code?" - ---- - -## Quick Reference - -### Standard Format Template - -``` -Brief summary line (50-72 chars) - -## Section 1: What Changed -- Bullet point 1 -- Bullet point 2 - -## Section 2: Why -- Rationale 1 -- Rationale 2 - -## Metrics (if applicable) -- Quantifiable outcome 1 -- Quantifiable outcome 2 - -Generated with [AI Tool] using [Model Name] - -Co-Authored-By: [Model Name] -``` - -### Minimal Format (Small Changes) - -``` -Brief summary line - -Single paragraph explaining change rationale. - -Generated with [AI Tool] using [Model Name] - -Co-Authored-By: [Model Name] -``` - ---- - -## Core Principles - -- **Context Over Brevity**: Comprehensive context more valuable than short messages -- **Structured Format**: Sections (What/Why/Metrics) improve scannability -- **Evidence-Based**: Include metrics, file counts, quantifiable outcomes -- **Model Attribution**: Identify which AI model contributed (debugging, capability tracking) -- **Archaeological Trail**: Future self needs to understand decisions, not just changes -- **Imperative Mood**: "Add feature" not "Added feature" or "Adds feature" - ---- - -## When to Apply - -**Always**: -- All commits (no exceptions) -- Feature additions -- Bug fixes -- Refactoring -- Documentation updates -- Configuration changes - -**Format Selection**: -- **Standard format**: Complex changes, multiple files, strategic decisions -- **Minimal format**: Small changes, single file, obvious rationale -- **Extended format**: Strategic checkpoints, learning integration, architectural decisions - ---- - -## Standard Format (Detailed) - -### Summary Line - -**Purpose**: One-line description of change that appears in `git log --oneline` - -**Guidelines**: -- **Length**: 50-72 characters (GitHub preview cutoff) -- **Mood**: Imperative ("Add feature" not "Added feature") -- **Content**: What was done, not why (why goes in body) -- **Specificity**: Concrete action, not vague descriptor - -**Examples**: -``` -Good: -Add retry logic to API client -Fix race condition in async handler -Update Pattern Library with validation checkpoints - -Bad (too vague): -Update files -Make changes -Fix bug -Improve code -``` - ---- - -### Body Structure - -#### Section 1: What Changed - -**Purpose**: Enumerate specific changes made in this commit - -**Format**: -```markdown -## What Changed -- Created validation_framework.py (127 lines) -- Updated 6 templates with new validation section -- Added validation pattern to Pattern Library -- Updated workflow guide with new steps -``` - -**Guidelines**: -- Bullet list format (easy to scan) -- File names with line counts (scope indication) -- Section names for docs/wiki (navigation aid) -- Versions if applicable - ---- - -#### Section 2: Why - -**Purpose**: Explain rationale - why was this change necessary? - -**Format**: -```markdown -## Why -- Previous approach caused data inconsistency under concurrent access -- New pattern prevents race conditions by using atomic operations -- Follows established patterns from similar systems -``` - -**Guidelines**: -- Answer "why now?" and "why this way?" -- Reference evidence (issues, retrospectives) -- Connect to broader context (patterns, principles) -- Include trade-offs if applicable - ---- - -#### Section 3: Metrics (Optional) - -**Purpose**: Quantify impact of change - -**Format**: -```markdown -## Metrics -- Response time reduced from 500ms to 50ms (90% improvement) -- 3 test files created (127, 83, 241 lines) -- Test coverage increased from 85% to 92% -``` - -**When to Include**: -- File size changes -- Performance improvements -- Quality improvements (test coverage, error rates) -- Refactoring scope (files touched, lines changed) - ---- - -### Footer: Model Attribution - -**Purpose**: Identify which AI model contributed to this code - -**Format**: -```markdown -Generated with [AI Tool] using [Model Name] - -Co-Authored-By: [Model Name] -``` - -**Why Model Attribution Matters**: -1. **Debugging**: Different models have different capabilities/limitations -2. **Capability Tracking**: Which models worked on which components -3. **Credit**: Acknowledge AI contribution explicitly -4. **Archaeology**: Understand context of code decisions - ---- - -## Format Variations - -### Minimal Format (Small Changes) - -**When to Use**: -- Single file changes -- Obvious rationale -- No strategic significance -- Quick fixes - -**Example**: -``` -Fix typo in Pattern Library - -Corrected "occurance" to "occurrence" in validation section. -No functional changes. - -Generated with Claude Code using Claude Sonnet - -Co-Authored-By: Claude Sonnet -``` - ---- - -### Extended Format (Strategic Checkpoints) - -**When to Use**: -- Strategic checkpoints -- Learning integration -- Architectural decisions -- Milestone completions - -**Template**: -``` -Brief summary line - -## Context -[Why this work was needed, broader picture] - -## What Changed -- Major change 1 -- Major change 2 - -## Why -- Strategic rationale 1 -- Strategic rationale 2 - -## Learning Integration -- Pattern 1: [Evidence] -> [Integration] -- Pattern 2: [Evidence] -> [Integration] - -## Metrics -- Quantifiable outcome 1 -- Quantifiable outcome 2 - -## Next Steps (optional) -- Follow-up action 1 -- Follow-up action 2 - -Generated with [AI Tool] using [Model Name] - -Co-Authored-By: [Model Name] -``` - ---- - -## Examples - -### Example 1: Feature Addition - -``` -Add retry logic to API client - -## What Changed -- Added exponential backoff retry wrapper to api_client.py -- Updated tests with retry scenarios (5 new tests) -- Added retry configuration to config.yaml - -## Why -- Production API calls occasionally timeout (3% failure rate) -- Immediate failures cause user-visible errors -- Retry with backoff provides resilience without overwhelming API - -## Metrics -- Failure rate reduced from 3% to 0.5% (83% improvement) -- Average retry count: 1.2 attempts per successful request -- P99 latency increased 200ms (acceptable trade-off) - -Generated with Claude Code using Claude Sonnet - -Co-Authored-By: Claude Sonnet -``` - ---- - -### Example 2: Bug Fix - -``` -Fix race condition in async request handler - -## What Changed -- Added mutex lock to request_queue in async_handler.py -- Updated 3 tests to verify thread-safety - -## Why -- Users reported "duplicate request processed" errors -- Root cause: Multiple threads accessing request_queue concurrently -- Mutex ensures only one thread modifies queue at a time - -## Metrics -- "Duplicate request" errors: 5 reports -> 0 reports (post-fix) -- Lock contention: < 1ms average wait time (negligible impact) - -Generated with Claude Code using Claude Sonnet - -Co-Authored-By: Claude Sonnet -``` - ---- - -### Example 3: Refactoring - -``` -Extract validation logic to separate module - -## What Changed -- Created validation.py with 6 validation functions -- Refactored api_handler.py to use validation module (-147 lines) -- Refactored data_processor.py to use validation module (-89 lines) -- Added 12 validation tests - -## Why -- Validation logic duplicated across 3 modules (DRY violation) -- Inconsistent validation (email regex differed between modules) -- Centralized validation enables consistent rules and easier testing - -## Metrics -- Duplication eliminated: 236 lines removed, 94 lines created (net -142) -- Test coverage: 85% -> 92% -- Validation consistency: 3 implementations -> 1 canonical - -Generated with Claude Code using Claude Sonnet - -Co-Authored-By: Claude Sonnet -``` - ---- - -## Validation Checklist - -**Before committing**: - -### Summary Line -- [ ] 50-72 characters -- [ ] Imperative mood ("Add" not "Added") -- [ ] Specific action, not vague -- [ ] Descriptive of what changed - -### Body -- [ ] What Changed section (bullet list) -- [ ] Why section (rationale with evidence) -- [ ] Metrics section (if applicable) -- [ ] Sections clearly labeled -- [ ] Evidence references where relevant - -### Footer -- [ ] Model attribution present -- [ ] Model name accurate -- [ ] Co-Authored-By format correct - -### Overall -- [ ] Archaeological value (future self can understand context) -- [ ] No placeholder text ("TODO", "TBD") -- [ ] Quantifiable metrics where possible - ---- - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| Summary line too long | Too much detail in summary | Move detail to body | -| Body feels empty | Minimal changes | Use minimal format for small changes | -| "What Changed" vs "Why" confused | Unclear distinction | What = enumeration, Why = rationale | -| Metrics section unclear | Uncertain what to measure | File counts, size changes, test coverage | - ---- - -**Success Criteria**: Commits provide context-rich messages with proper structure, model attribution, and archaeological value for future understanding. diff --git a/.pongogo/instructions/software_engineering/python_script_development.instructions.md b/.pongogo/instructions/software_engineering/python_script_development.instructions.md deleted file mode 100644 index a3d02fc9..00000000 --- a/.pongogo/instructions/software_engineering/python_script_development.instructions.md +++ /dev/null @@ -1,459 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Python Script Development Standards" -description: "Standards for Python script development including structure, testing, and best practices." -applies_to: - - "**/*" -domains: - - "software_engineering" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 1 - triggers: - keywords: - - python_script - - argparse - - type_hints - - pathlib - - python_logging - - mypy - - pytest - - python_error_handling - - python_cli - - python_template - nlp: "Python script development with type hints, argparse CLI, pathlib file operations, logging module, pytest testing" -evaluation: - success_signals: - - All functions have type hints (parameters and return types) - - argparse used with --help, --debug, --log-level, --dry-run flags - - Pathlib.Path used for all file operations (not string manipulation) - - Specific exceptions caught (not bare except clauses) - - Script structured for testability with main() and __name__ guard - failure_signals: - - Functions missing type annotations (mypy errors) - - sys.argv used directly instead of argparse - - String path manipulation breaking on Windows - - Bare except clauses catching KeyboardInterrupt/SystemExit - - Logic at module level executing on import (not testable) ---- - - -# Python Script Development Standards - -**Purpose**: Establish comprehensive standards for developing and maintaining Python scripts with type safety, proper argument parsing, error handling, and systematic prevention patterns. - -**Philosophy**: Python scripts should leverage Python's strengths - type hints for clarity, rich standard library for robustness, and testing frameworks for reliability. - ---- - -## When to Apply - -Use these Python scripting standards when: - -- Writing new Python scripts for project workflows -- Building CLI tools or automation scripts -- Creating data processing or analysis scripts -- Writing migration or maintenance scripts -- Refactoring legacy Python code -- Building scripts that interact with APIs or databases - ---- - -## Quick Reference - -**Key Python Script Patterns (Code Examples)**: - -**1. Script Template with Safety Flags**: -```python -#!/usr/bin/env python3 -""" -script-name.py - Brief description of what this script does - -Usage: - ./script-name.py --dry-run - ./script-name.py --debug - ./script-name.py --log-level warn -""" - -import argparse -import logging -import sys -from pathlib import Path -from typing import List, Optional, Dict, Any - -logger = logging.getLogger(__name__) - - -def setup_logging(log_level: str = "info", debug: bool = False) -> None: - """Configure logging based on CLI flags.""" - if debug: - level = logging.DEBUG - else: - level = getattr(logging, log_level.upper(), logging.INFO) - - logging.basicConfig( - level=level, - format='[%(levelname)s] %(message)s' - ) - - -def main() -> int: - """Main function. Returns: Exit code (0 = success, 1 = error).""" - parser = argparse.ArgumentParser(description='Script description') - - parser.add_argument('-d', '--dry-run', action='store_true', - help='Show what would be done without making changes') - parser.add_argument('--debug', action='store_true', - help='Show DEBUG messages in terminal') - parser.add_argument('--log-level', default='info', - choices=['info', 'warn', 'error'], - help='Set log level (default: info)') - - args = parser.parse_args() - setup_logging(log_level=args.log_level, debug=args.debug) - - if args.dry_run: - print("[DRY-RUN MODE] No changes will be made\n") - - logger.debug("Debug message - only shown with --debug") - logger.info("Info message - shown at info level and above") - - # Main logic here - return 0 - - -if __name__ == '__main__': - sys.exit(main()) -``` - -**2. Type Hints for Everything**: -```python -from typing import List, Dict, Optional, Tuple, Any -from pathlib import Path - -def process_files( - file_paths: List[Path], - output_dir: Path, - dry_run: bool = False -) -> Tuple[int, int]: - """ - Process multiple files. - - Args: - file_paths: List of input file paths - output_dir: Output directory - dry_run: If True, don't make changes - - Returns: - Tuple of (success_count, failure_count) - """ - success_count = 0 - failure_count = 0 - - for file_path in file_paths: - if process_single_file(file_path, output_dir, dry_run): - success_count += 1 - else: - failure_count += 1 - - return success_count, failure_count - - -def parse_config(config_path: Path) -> Optional[Dict[str, Any]]: - """ - Parse configuration file. - - Returns: - Config dictionary, or None if parsing failed - """ - try: - import yaml - content = config_path.read_text() - return yaml.safe_load(content) - except Exception as e: - logger.error(f"Failed to parse config: {e}") - return None -``` - -**3. Pathlib for File Operations**: -```python -from pathlib import Path - -# Pathlib is more Pythonic and cross-platform -file_path = Path("/path/to/file.txt") -directory = file_path.parent -new_path = directory / "new_file.txt" - -# Pathlib operations -if file_path.exists(): - content = file_path.read_text(encoding='utf-8') - file_path.write_text("new content", encoding='utf-8') - -# Recursive glob -md_files = list(Path("docs").rglob('*.md')) - -# Path components -name = file_path.name # file.txt -stem = file_path.stem # file -suffix = file_path.suffix # .txt -parent = file_path.parent # /path/to - -# Absolute path -abs_path = file_path.resolve() -``` - -**4. Structured Error Handling**: -```python -from pathlib import Path -from typing import Optional - -def read_file_safely(file_path: Path) -> Optional[str]: - """Read file with comprehensive error handling.""" - try: - return file_path.read_text(encoding='utf-8') - - except FileNotFoundError: - logger.error(f"File not found: {file_path}") - logger.error(f"Current directory: {Path.cwd()}") - return None - - except PermissionError: - logger.error(f"Permission denied: {file_path}") - return None - - except UnicodeDecodeError as e: - logger.error(f"Encoding error: {e}") - return None - - except Exception as e: - logger.error(f"Unexpected error: {e}") - logger.exception("Full traceback:") - return None -``` - -**5. Argparse CLI Pattern**: -```python -def main() -> int: - parser = argparse.ArgumentParser( - description='Process files with validation', - formatter_class=argparse.RawDescriptionHelpFormatter, - epilog=''' -Examples: - %(prog)s --dry-run - %(prog)s --verbose - %(prog)s --debug --dry-run - ''' - ) - - parser.add_argument('-d', '--dry-run', action='store_true', - help='Show what would be done') - parser.add_argument('-v', '--verbose', action='store_true', - help='Enable verbose logging') - parser.add_argument('--debug', action='store_true', - help='Enable debug mode') - parser.add_argument('--input-dir', type=Path, - default=Path('.'), - help='Input directory') - - args = parser.parse_args() - setup_logging(args.verbose, args.debug) - - if args.dry_run: - print("[DRY-RUN MODE]\n") - - return 0 -``` - -**6. Structure for Testing**: -```python -#!/usr/bin/env python3 -"""analyze-files.py - Analyze file metrics""" - -from pathlib import Path -from typing import Dict, List - -def count_lines(file_path: Path) -> int: - """Count lines in file.""" - return len(file_path.read_text().splitlines()) - -def count_examples(content: str) -> int: - """Count example blocks.""" - return content.count('```') - -def analyze_file(file_path: Path) -> Dict[str, int]: - """Analyze single file.""" - content = file_path.read_text() - return { - 'lines': count_lines(file_path), - 'examples': count_examples(content), - 'characters': len(content) - } - -def main() -> int: - """Main function.""" - directory = Path('docs') - if not directory.exists(): - print(f"Error: Directory not found: {directory}") - return 1 - - for file_path in directory.rglob('*.md'): - metrics = analyze_file(file_path) - print(f"{file_path.name}: {metrics}") - - return 0 - -if __name__ == '__main__': - import sys - sys.exit(main()) -``` - -**7. Type Checking & Linting**: -```bash -# Run type checker -mypy script.py - -# Run linter -pylint script.py -# or -ruff check script.py - -# Run formatter -black script.py - -# Run tests -pytest test_script.py -v -``` - ---- - -## Core Principles - -- **Type Hints Everywhere**: All functions have type annotations for inputs and outputs -- **Argparse for CLI**: Use argparse (not sys.argv) for command-line argument parsing -- **Validation Before Execution**: Every script implements --dry-run flag -- **Structured Logging**: Use logging module, not print statements -- **Error-Specific Handling**: Catch specific exceptions, not bare `except:` -- **Pathlib for Paths**: Use Path objects, not string manipulation -- **Context Managers**: Use `with` for resources (files, connections, locks) -- **Docstrings Required**: All functions and modules have docstrings -- **Testing First-Class**: Scripts structured for testability with pytest - -## Step-by-Step Guidance - -### 1. **Start with Script Template** - - Add shebang: `#!/usr/bin/env python3` - - Add module docstring describing script purpose - - Import standard library first, then third-party, then local - - Expected outcome: Well-structured imports and documentation - -### 2. **Implement Argparse with Required Flags** - - Use argparse.ArgumentParser for all CLI arguments - - **Required flags** (all scripts must implement): - - `--help, -h`: Automatically provided by argparse - - `--debug`: Show DEBUG messages in terminal - - `--log-level`: Control log verbosity (`info`, `warn`, `error`) - - `--dry-run, -d`: Show what would be done without making changes - - Expected outcome: Consistent CLI interface with standard flags - -### 3. **Configure Logging** - - Use logging module instead of print statements - - Set log level based on --log-level flag; --debug enables DEBUG - - Use structured log format with timestamps - - Expected outcome: Configurable, structured logging - -### 4. **Add Type Hints** - - Annotate all function parameters with types - - Annotate return types (including `-> None`) - - Use typing module for complex types (List, Dict, Optional) - - Expected outcome: Type-safe code that passes mypy - -### 5. **Implement Error Handling** - - Catch specific exceptions (IOError, ValueError, etc.) - - Log errors with context before raising/returning - - Return exit codes (0 = success, 1+ = error) - - Expected outcome: Clear error messages with recovery guidance - -### 6. **Use Pathlib for File Operations** - - Import Path from pathlib - - Use Path objects for all file paths - - Use Path methods (exists(), read_text(), etc.) - - Expected outcome: Cross-platform path handling - -### 7. **Structure for Testability** - - Logic in functions, not at module level - - Main logic in main() function - - Use `if __name__ == '__main__'` guard - - Expected outcome: Functions can be imported and tested - -## Validation Checklist - -Before considering a Python script complete: - -- [ ] Shebang present: `#!/usr/bin/env python3` -- [ ] Module docstring describing purpose -- [ ] All functions have type hints -- [ ] All functions have docstrings -- [ ] Argparse used for CLI arguments -- [ ] **Required CLI flags implemented**: - - [ ] `--help, -h` (automatic with argparse) - - [ ] `--debug` (show DEBUG messages) - - [ ] `--log-level` (`info`, `warn`, `error`) - - [ ] `--dry-run, -d` (for scripts that modify data) -- [ ] Logging module used (not print statements) -- [ ] Specific exception handling (not bare `except:`) -- [ ] Pathlib used for all file paths -- [ ] `if __name__ == '__main__'` guard present -- [ ] Main logic in `main()` function returning exit code -- [ ] Script tested with `--dry-run` and `--help` -- [ ] mypy passes with no type errors -- [ ] pytest tests written for core functions - -## Common Pitfalls - -### Pitfall 1: Bare `except:` Clauses - -- **Problem**: Catches all exceptions including KeyboardInterrupt, SystemExit -- **Why it happens**: Lazy exception handling -- **Solution**: Catch specific exceptions (IOError, ValueError, etc.) - -### Pitfall 2: Using `sys.argv` Instead of argparse - -- **Problem**: Manual argument parsing is error-prone, no `--help` generation -- **Why it happens**: Thinking argparse is overkill for simple scripts -- **Solution**: Always use argparse, even for simple scripts - -### Pitfall 3: String Path Manipulation - -- **Problem**: Path joining with `+` or `/` breaks on Windows -- **Why it happens**: Not using pathlib -- **Solution**: Use Path objects for all file paths - -### Pitfall 4: Missing Type Hints - -- **Problem**: Functions unclear, type errors not caught -- **Why it happens**: Treating Python as dynamically typed -- **Solution**: Add type hints to all functions - -### Pitfall 5: Logic at Module Level - -- **Problem**: Script runs immediately on import, can't test functions -- **Why it happens**: Not using `if __name__ == '__main__'` guard -- **Solution**: Put logic in functions, call from `main()`, use guard - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| mypy type errors | Missing or incorrect type hints | Add type annotations, import from typing module | -| Script runs on import | No `if __name__ == '__main__'` guard | Add guard around main() call | -| Path errors on Windows | String path manipulation | Use pathlib.Path for all paths | -| Can't interrupt script | Bare `except:` catches KeyboardInterrupt | Catch specific exceptions only | -| No --help output | Not using argparse | Replace sys.argv with argparse | -| Encoding errors | Not specifying encoding | Use `encoding='utf-8'` in file operations | - ---- - -**Success Criteria**: All Python scripts use type hints, argparse, logging module, pathlib, implement safety flags, and have pytest tests. mypy passes with no errors. diff --git a/.pongogo/instructions/testing/observability_testing.instructions.md b/.pongogo/instructions/testing/observability_testing.instructions.md deleted file mode 100644 index 893695c1..00000000 --- a/.pongogo/instructions/testing/observability_testing.instructions.md +++ /dev/null @@ -1,539 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Observability Testing" -description: "Testing standards for observability, monitoring, and diagnostic instrumentation." -applies_to: - - "**/*" -domains: - - "testing" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 1 - triggers: - keywords: - - observability_testing - - log_isolation - - test_isolation - - five-test_framework - - JSONL_validation - - data_capture - - validation_suite - - cross-contamination - - sequential_testing - - backward_compatibility - nlp: "Testing observability systems with log isolation, five-test validation framework, data capture verification, and cross-contamination prevention" -evaluation: - success_signals: - - All 5 validation tests pass (standard, testing, learning, backward compat, invalid) - - Logs isolated correctly with no cross-contamination between modes - - Data format verified (JSONL parseable by standard tools) - - Database rebuildable from JSONL source of truth - - Tests run sequentially to verify isolation from previous tests - failure_signals: - - Tests run in parallel losing isolation verification - - Cross-contamination detected between production and testing logs - - Missing backward compatibility testing (legacy state files) - - JSONL format validation skipped (trusting without verification) - - Silent failures on invalid configuration values ---- - - -# Observability Testing Patterns - -**Purpose**: Define systematic testing approach for observability systems ensuring data capture, validation, and operational readiness across multiple isolation modes. - -**Philosophy**: Observability systems require multi-dimensional validation (functionality, data completeness, performance, isolation) beyond standard feature testing. - ---- - -## When to Apply - -- Testing logging or observability systems -- Validating data capture pipelines -- Implementing log isolation strategies (test/production/learning separation) -- Preparing observability for production deployment -- Verifying data completeness and format correctness -- Testing backward compatibility with legacy configurations - ---- - -## Quick Reference - -**Five-Test Framework for Observability Validation**: -1. **Standard Mode**: Default production configuration -2. **Isolation Mode 1**: First alternative mode (e.g., testing) -3. **Isolation Mode 2**: Second alternative mode (e.g., learning) -4. **Backward Compatibility**: Missing/legacy configuration -5. **Invalid Input**: Validation and error handling - -**Success Criteria per Test**: -- Data captured in correct location -- Correct isolation (no cross-contamination) -- Database/index updated if applicable -- Performance within limits -- No silent failures - ---- - -## Core Principles - -- **Test Isolation**: Production and test data must never mix - parameter-based routing prevents cross-contamination -- **Multi-Dimensional Validation**: Verify functionality, data format, performance, and storage in every test -- **Sequential Execution**: Tests must run in order to verify isolation from previous tests -- **No Silent Failures**: Invalid configurations must fail loudly with actionable error messages -- **Data as Source of Truth**: JSONL/immutable formats are authoritative, indexes/databases are rebuildable - -## Step-by-Step Guidance - -### 1. Design Log Isolation Strategy - -**Action**: Implement parameter-based routing to separate directories - -**Implementation**: -```python -def get_log_paths(state, project_root): - """Route logs based on isolation parameter.""" - log_comment = state.get('log_comment', '') - - if log_comment == 'testing': - return project_root / "logs/logs-testing" - elif log_comment == 'learning': - return project_root / "logs/logs-learning" - else: - # Standard production (empty or unset) - return project_root / "logs/logs-production" -``` - -**Why This Matters**: -- Prevents production data pollution during testing -- Enables safe A/B testing without impacting real data -- Supports dataset collection for learning/training - -**Success Indicator**: Test data routes to separate directory, production logs unchanged - ---- - -### 2. Create Five-Test Validation Suite - -**Action**: Design tests covering all operational modes plus edge cases - -**Test Suite Structure**: - -**Test 1: Standard Production Mode** -- Configuration: Default/production settings (parameter empty or unset) -- Expected: Data routes to production location -- Validation: Check file exists, entry count, content format - -**Test 2: Isolation Mode 1 (Testing)** -- Configuration: Testing mode parameter set (`log_comment="testing"`) -- Expected: Data routes to testing location, isolated from production -- Validation: Production logs unchanged, testing logs created - -**Test 3: Isolation Mode 2 (Learning)** -- Configuration: Learning mode parameter set (`log_comment="learning"`) -- Expected: Data routes to learning location -- Validation: Both production and testing logs unchanged - -**Test 4: Backward Compatibility** -- Configuration: Missing parameter key (simulates old state file) -- Expected: Graceful degradation to production mode -- Validation: No errors, defaults to production location correctly - -**Test 5: Invalid Input Validation** -- Configuration: Invalid parameter value (`log_comment="invalid"`) -- Expected: Clear error raised, no silent failure -- Validation: `ValueError` with actionable message, no partial writes - -**Execution Order**: Must be sequential, not parallel -- Each test verifies isolation from previous tests -- Cross-contamination detection requires ordered execution - ---- - -### 3. Verify Data Capture Completeness - -**Action**: Validate captured data meets format and completeness requirements - -**What to Verify**: -```bash -# 1. Format correctness (JSONL parseable) -tail -1 logs/logs-production/events.jsonl | python3 -m json.tool - -# 2. Entry count matches expectations -wc -l logs/logs-production/events.jsonl - -# 3. Database exists and is reasonable size -ls -lh .observability_db/observability_db-production/routing_log-production.db - -# 4. No cross-contamination -wc -l logs/logs-testing/events.jsonl # Should only have Test 2 entry -``` - -**Success Criteria**: -- All JSONL entries parseable by standard tools (jq, python json.tool) -- Entry counts match test execution (1 per test in correct location) -- Database files created with reasonable sizes -- Zero entries in isolation directories when not in that mode - ---- - -### 4. Validate Rebuild Capability - -**Action**: Verify immutable source (JSONL) can rebuild queryable index (SQLite/other) - -**Test Procedure**: -1. Capture events to JSONL (primary source) -2. Build SQLite database from JSONL -3. Delete SQLite database -4. Rebuild SQLite from JSONL -5. Verify queries return identical results - -**Why This Matters**: -- JSONL is source of truth (Git-tracked, immutable, append-only) -- SQLite/indexes are ephemeral (`.gitignore`'d, rebuildable from source) -- Must be able to recover from database corruption/loss without data loss - -**Example**: -```bash -# Query current database state -sqlite3 .observability_db/observability_db-production/routing_log-production.db "SELECT COUNT(*) FROM routing_events" > before.txt - -# Simulate corruption by deleting database -rm .observability_db/observability_db-production/routing_log-production.db - -# Trigger adapter (send any message) - adapter auto-recovers -# Next routing event will: -# 1. Detect missing/invalid database -# 2. Automatically reinitialize schema -# 3. Continue writing events - -# Verify database recreated (will only have NEW events, not historical) -sqlite3 .observability_db/observability_db-production/routing_log-production.db "SELECT COUNT(*) FROM routing_events" - -# Historical data remains in JSONL (source of truth) -wc -l logs/logs-production/routing-events-*.jsonl -``` - ---- - -### 5. Measure Storage Overhead - -**Action**: Validate storage requirements are acceptable - -**Metrics to Track**: -- JSONL size per event (average, max) -- Database size growth rate -- Total storage for N events -- Acceptable limit (e.g., <100MB for 1000 events) - -**Example Measurement**: -```bash -# Measure after validation tests -du -sh logs/ -du -sh .observability_db/ - -# Calculate per-event average -EVENTS=$(wc -l < logs/logs-production/events.jsonl) -SIZE=$(du -sb logs/logs-production/events.jsonl | cut -f1) -echo "Average: $((SIZE / EVENTS)) bytes/event" -``` - -**Decision Framework**: -- <100KB per 100 events: Excellent -- 100KB-500KB per 100 events: Acceptable -- >500KB per 100 events: Investigate (possible data bloat) - ---- - -## Examples - -### Example 1: Complete Validation Suite (Bash Script) - -```bash -#!/bin/bash -# complete_observability_validation.sh - -echo "=== Observability Validation Suite ===" -echo "" - -# Test 1: Standard Production Mode -echo "Test 1: Standard Production Mode" -python3 scripts/toggle_mode.py --mode enabled -# Submit test message here -sleep 2 -if [ -f logs/logs-production/events.jsonl ]; then - echo "✅ Production log created" - wc -l logs/logs-production/events.jsonl -else - echo "❌ Production log missing" - exit 1 -fi - -# Test 2: Testing Mode -echo "" -echo "Test 2: Testing Mode" -python3 scripts/toggle_mode.py --mode enabled --log-comment testing -# Submit test message here -sleep 2 -if [ -f logs/logs-testing/events.jsonl ]; then - echo "✅ Testing log created" - # Verify production unchanged - PROD_COUNT=$(wc -l < logs/logs-production/events.jsonl) - if [ "$PROD_COUNT" -eq 1 ]; then - echo "✅ Production isolated (still 1 entry)" - else - echo "❌ Production contaminated" - exit 1 - fi -else - echo "❌ Testing log missing" - exit 1 -fi - -# Test 3: Learning Mode -echo "" -echo "Test 3: Learning Mode" -python3 scripts/toggle_mode.py --mode enabled --log-comment learning -# Submit test message here -sleep 2 -if [ -f logs/logs-learning/events.jsonl ]; then - echo "✅ Learning log created" - # Verify both production and testing unchanged - PROD_COUNT=$(wc -l < logs/logs-production/events.jsonl) - TEST_COUNT=$(wc -l < logs/logs-testing/events.jsonl) - if [ "$PROD_COUNT" -eq 1 ] && [ "$TEST_COUNT" -eq 1 ]; then - echo "✅ Production and testing isolated" - else - echo "❌ Cross-contamination detected" - exit 1 - fi -else - echo "❌ Learning log missing" - exit 1 -fi - -# Test 4: Backward Compatibility -echo "" -echo "Test 4: Backward Compatibility" -# Remove log_comment key from state file -python3 -c "import json; state = json.load(open('.state.json')); del state['log_comment']; json.dump(state, open('.state.json', 'w'))" -# Submit test message here -sleep 2 -PROD_COUNT=$(wc -l < logs/logs-production/events.jsonl) -if [ "$PROD_COUNT" -eq 2 ]; then - echo "✅ Backward compatibility: defaulted to production" -else - echo "❌ Backward compatibility failed" - exit 1 -fi - -# Test 5: Invalid Value Validation -echo "" -echo "Test 5: Invalid Value Validation" -python3 scripts/toggle_mode.py --mode enabled --log-comment invalid 2>&1 | grep -q "Invalid log_comment" -if [ $? -eq 0 ]; then - echo "✅ Invalid value rejected correctly" -else - echo "❌ Invalid value not rejected" - exit 1 -fi - -echo "" -echo "=== All Tests Passed ✅ ===" -``` - -**Context**: Complete end-to-end validation script for observability system with 5 isolation tests - -**Expected Result**: All 5 tests pass, logs created in correct locations, no cross-contamination detected - ---- - -### Example 2: Data Format Validation (Python) - -```python -#!/usr/bin/env python3 -"""Validate JSONL format and schema correctness.""" - -import json -import sys -from pathlib import Path - -def validate_jsonl_file(file_path: Path) -> tuple[bool, list[str]]: - """ - Validate JSONL file format and schema. - - Returns: - (success, errors): Boolean success and list of error messages - """ - errors = [] - - if not file_path.exists(): - return False, [f"File not found: {file_path}"] - - try: - with open(file_path) as f: - for line_num, line in enumerate(f, 1): - line = line.strip() - if not line: - continue - - try: - # Validate JSON parseable - event = json.loads(line) - - # Validate required fields - required_fields = ['timestamp', 'message', 'mode'] - missing = [f for f in required_fields if f not in event] - if missing: - errors.append(f"Line {line_num}: Missing fields {missing}") - - # Validate mode value - valid_modes = ['enabled', 'disabled', 'simulate'] - if event.get('mode') not in valid_modes: - errors.append(f"Line {line_num}: Invalid mode '{event.get('mode')}'") - - except json.JSONDecodeError as e: - errors.append(f"Line {line_num}: JSON decode error: {e}") - - except Exception as e: - return False, [f"Error reading file: {e}"] - - return len(errors) == 0, errors - -# Usage -if __name__ == '__main__': - file_path = Path(sys.argv[1]) - success, errors = validate_jsonl_file(file_path) - - if success: - print(f"✅ {file_path}: Valid JSONL format") - sys.exit(0) - else: - print(f"❌ {file_path}: Validation failed") - for error in errors: - print(f" - {error}") - sys.exit(1) -``` - -**Context**: Standalone validation script for JSONL format and schema correctness - -**Usage**: `python3 validate_jsonl.py logs/logs-production/events.jsonl` - ---- - -## Validation Checklist - -- [ ] Log isolation implemented (parameter-based routing) -- [ ] Five-test validation suite created and passing -- [ ] Data format validation passing (JSONL parseable) -- [ ] Entry counts match expectations (1 per test in correct location) -- [ ] Database/index created correctly -- [ ] Rebuild from source works (delete DB, rebuild, verify) -- [ ] Storage overhead acceptable (<100KB per 100 events) -- [ ] Cross-contamination tests passing (isolation verified) -- [ ] Backward compatibility verified (missing parameter defaults) -- [ ] Invalid input rejected (ValueError raised with clear message) -- [ ] Performance within limits (latency, overhead measured) - ---- - -## Common Pitfalls - -### Pitfall 1: Testing All Modes in Parallel - -- ❌ **Problem**: Running all 5 tests concurrently loses isolation verification -- **Why it happens**: Attempting to speed up test execution -- ✅ **Solution**: Run tests sequentially to verify no cross-contamination -- **Example**: Test 2 must verify production logs unchanged from Test 1 - -### Pitfall 2: Skipping Backward Compatibility Testing - -- ❌ **Problem**: Legacy state files without new parameters cause silent failures -- **Why it happens**: Assuming all installations have latest state file format -- ✅ **Solution**: Always test with missing parameter key (graceful degradation) -- **Example**: Old state file without `log_comment` key should default to production - -### Pitfall 3: Trusting Format Without Verification - -- ❌ **Problem**: JSONL may be malformed but tests pass anyway -- **Why it happens**: Not validating with standard tools (jq, json.tool) -- ✅ **Solution**: Run format validation on every test log file -- **Example**: `tail -1 logs/logs-testing/events.jsonl | python3 -m json.tool` - -### Pitfall 4: Batch Testing Before Refactoring - -- ❌ **Problem**: Running all tests before fixing structural issues revealed by Test 1 -- **Why it happens**: Attempting to batch all testing before any fixes -- ✅ **Solution**: If Test 1 reveals structural issues, refactor immediately before Tests 2-5 -- **Example**: Directory refactoring between Test 1 and Tests 2-5 for 0% rework - ---- - -## Edge Cases - -### Edge Case 1: Very Large Messages - -**When**: Observability system captures messages >100KB (code snippets, large diffs) - -**Approach**: Implement message truncation or excerpt strategy -- Store full message in JSONL (source of truth) -- Store excerpt in database (for display/search) -- Provide link/reference to full content - -**Example**: -```python -def format_message_excerpt(message: str, max_length: int = 500) -> str: - """Truncate message for database storage.""" - if len(message) <= max_length: - return message - return message[:max_length] + "... (truncated)" -``` - -### Edge Case 2: Rapid Mode Switching - -**When**: Tests switch between modes rapidly (< 1 second apart) - -**Approach**: Add small delay or state verification -- Verify state file written before triggering event -- Add 1-2 second delay between mode switches -- Check adapter has reloaded state before proceeding - -### Edge Case 3: Disk Space Exhaustion - -**When**: Observability logs grow unbounded until disk full - -**Approach**: Implement rotation and cleanup strategy -- Daily rotation: `logs-YYYY-MM-DD.jsonl` -- Automatic cleanup: Delete logs older than N days -- Storage limits: Alert when >X% disk usage - ---- - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| Logs not created | State file not updated | Verify state file written correctly before test | -| Wrong directory | Parameter not read | Check adapter reads state before routing | -| Cross-contamination | Parallel execution | Run tests sequentially, verify isolation | -| Format errors | Invalid JSON | Validate each line with `python3 -m json.tool` | -| Database missing | Dual-write failed | Check adapter writes to both JSONL and DB | -| Rebuild fails | JSONL corrupted | Validate JSONL format, check for truncation | -| Silent failures | Missing validation | Add strict parameter validation with ValueError | - ---- - -## Related Instructions - -- **See also**: [Validation Essentials](../workflow/validation_essentials.instructions.md) - General validation principles -- **Prerequisites**: [Deterministic Validation Framework](../decision/deterministic_validation_framework.instructions.md) - 100% pass rate requirement -- **Related**: [Observability Patterns](../architecture/observability_patterns.instructions.md) - Comprehensive observability design - ---- - -**Success Criteria**: All 5 validation tests pass, logs isolated correctly, data format verified, storage overhead acceptable - -**Confidence Check**: Can you rebuild the database from JSONL and get identical query results? If yes, observability validation is complete. diff --git a/.pongogo/instructions/trust_execution/development_workflow_essentials.instructions.md b/.pongogo/instructions/trust_execution/development_workflow_essentials.instructions.md deleted file mode 100644 index ba1170d5..00000000 --- a/.pongogo/instructions/trust_execution/development_workflow_essentials.instructions.md +++ /dev/null @@ -1,680 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Development Workflow Essentials" -description: "Essential development workflow patterns, practices, and coordination standards." -applies_to: - - "**/*" -domains: - - "trust_execution" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 0 - triggers: - keywords: - - development_workflow - - complete_context - - phase_completion - - four-level_completion - - task_completion - - epic_completion - - milestone_completion - - evidence_summary - - trust_phases - - quality_gates - nlp: "Development workflow with complete context reading, four-level completion framework (phase/task/epic/milestone), trust-based phase execution, evidence-based progress tracking" -evaluation: - success_signals: - - Complete files read (never head/tail/truncation during development) - - Previous phase outputs trusted without re-analysis - - "Four-level completion followed (Phase -> Task -> Epic -> Milestone)" - - Evidence summary with specific artifacts linked (commits, files, tests) - - All SC/AC/CV items checked before marking complete - failure_signals: - - Partial context reading (head -n 100 or content.slice) - - Re-analyzing completed phases instead of trusting outputs - - Marking complete before all criteria items checked - - Completion comment says "done" without linked evidence - - Missing work log entries at task/epic/milestone completion ---- - - -# Development Workflow Essentials - -**Purpose**: Define essential workflow standards for feature development including complete context requirements, trust-based phase execution, and four-level completion framework. - -**Philosophy**: Complete context enables correct decisions, validated phases build foundational truth, and systematic completion tracking ensures nothing is missed. - ---- - -## When to Apply - -Use these standards when: - -- Implementing features for agent team systems -- Reading any file, issue, or content during development work -- Completing phases, tasks, Epics, or milestones -- Validating work meets quality gates before marking complete -- Coordinating work across multiple services - ---- - -## Quick Reference - -**Essential Workflow Patterns**: - -**1. Complete Context Reading** (ALWAYS): -```typescript -// ✅ Complete file reading -const fileContent = await readFile(filePath, 'utf-8'); // Full content -const issue = await octokit.issues.get({ issue_number: 42 }); // Complete issue - -// ❌ NEVER use partial reads during development -const preview = await head(filePath, 10); // WRONG - creates knowledge gaps -const snippet = content.slice(0, 1000); // WRONG - incomplete context -``` - -**2. Four-Level Completion Framework**: -``` -Level 1: Phase Complete -├─ Trigger: All Success Criteria items checked -├─ Actions: Update checkboxes + completion comment + (optional) work log -└─ Evidence: Commits, files, tests linked - -Level 2: Task Complete -├─ Trigger: ALL Acceptance Criteria AND ALL Completion Validation items checked -├─ Actions: Update checkboxes + completion comment + work log + close issue -└─ Evidence: All tests passing (100%), docs updated, integration validated - -Level 3: Epic Complete -├─ Trigger: ALL Epic tasks (1/X through X/X) closed -├─ Actions: Epic completion comment + work log + close Epic -└─ Evidence: All tasks closed, Epic objectives met, learnings captured - -Level 4: Milestone Complete -├─ Trigger: ALL milestone issues closed -├─ Actions: Retrospective doc + comprehensive work log + close milestone -└─ Evidence: All issues closed, objectives achieved, strategic summary -``` - -**3. Trusting Previous Phases**: -```markdown -Starting Validation Phase? -├─ Read implementation completion comment -├─ Extract implementation outputs and recommendations -├─ DO: Implement per implementation recommendations -├─ DO: Validate validation against validation criteria -├─ DON'T: Re-analyze implementation decisions -└─ DON'T: Question implementation validated work -``` - -**4. Phase Completion Evidence Template**: -```markdown -## Phase P## Complete - [Phase Name] - -**Evidence Summary**: -- ✅ P##.SC01: [What completed] ([Evidence: commit SHA, file, test]) -- ✅ P##.SC02: [What completed] ([Evidence]) -- ✅ P##.SC03: [What completed] ([Evidence]) - -**Implementation Highlights**: -- Key decision and rationale -- Trade-offs made -- Technical debt incurred (if any) - -**Next Phase**: P## - [Next Phase Name] -``` - -**5. Task Completion Validation Checklist**: -- [ ] All Success Criteria items checked with evidence -- [ ] All Acceptance Criteria items checked with validation docs -- [ ] All Completion Validation items checked with operational evidence -- [ ] All tests passing (100% deterministic pass rate) -- [ ] Documentation updated (code, API, user, architecture) -- [ ] Work log entry created with outcomes -- [ ] Issue closed with "Closes #X" in commit - -**6. When to Mark Complete vs Continue Work**: -``` -Can mark Phase complete? -├─ All SC items checked? NO → Continue implementation -└─ All SC items checked? YES → ✅ MARK COMPLETE + add evidence comment - -Can mark Task complete? -├─ All AC items checked? NO → Continue quality validation -├─ All CV items checked? NO → Continue operational validation -└─ All AC and CV checked? YES → ✅ MARK COMPLETE + close issue - -Can mark Epic complete? -├─ All Epic tasks closed? NO → Continue feature work -└─ All tasks closed? YES → ✅ MARK COMPLETE + capture learnings -``` - -**7. Complete Context Anti-Patterns** (AVOID): -- ❌ Using `head -n 100 file.md` → Read complete file -- ❌ Using `content.slice(0, 1000)` → Read complete content -- ❌ Scanning "first few lines" → Read entire file -- ❌ "Quick check" with partial read → Complete read every time - ---- - -## Core Principles - -- **Complete Context Requirement**: Always read complete files/content, never use partial reads (head/tail/truncation) -- **Trust Validated Phases**: When phase is marked complete with all checkboxes, trust outputs as foundational truth -- **Four-Level Completion**: Phase → Task → Epic → Milestone, each with specific completion requirements -- **Systematic Validation**: Every level has explicit Success Criteria, Acceptance Criteria, and Completion Validation -- **Evidence-Based Progress**: Document completion with evidence summary, not just checkbox marking - -## Step-by-Step Guidance - -### Step 1: Maintain Complete Context During Development - -Never use partial reads during feature development - always access complete content. - -1. **Use Complete Reading Methods**: - ```typescript - // ✅ Complete file reading - const fileContent = await readFile(filePath, 'utf-8'); // Full content - const issue = await octokit.issues.get({ issue_number: 42 }); // Complete issue - - // ❌ Never use partial reads - const preview = await head(filePath, 10); // WRONG - creates knowledge gaps - const snippet = content.slice(0, 1000); // WRONG - incomplete context - ``` - - Expected outcome: Complete understanding of content before making decisions - - Rationale: Partial context violates systematic prevention principles - -2. **Handle Large Files Properly**: - - Use pagination/batching for truly large files - - Process complete sections sequentially - - Never resort to sampling or truncation - - Success indicator: All relevant content processed, no gaps - -3. **Apply to All Development Reading**: - - GitHub issues and PR descriptions - - Instruction files and documentation - - Code files requiring modification - - Configuration files - - Integration point: Ensures decisions based on complete information - -### Step 2: Trust Completed Phases - -When phase is marked complete, trust the outputs without re-analyzing. - -1. **Read Previous Phase Outputs**: - ```markdown - ## Design Phase Complete - Requirements Analysis ✓ - - **Evidence Summary**: - - ✅ Design.SC01: User stories documented (see issue body) - - ✅ Design.SC02: Technical approach defined (see architecture doc) - - **Deliverables**: - - User story: "Agent creates task via routing service" - - Technical approach: REST API with TypeScript service - ``` - - Expected outcome: Use these outputs directly without questioning - -2. **Implement Based on Validated Outputs**: - - ✅ **DO**: Read previous phase outputs and implement directly - - ✅ **DO**: Validate current phase against its own criteria - - ❌ **DON'T**: Re-analyze or question validated previous phase work - - ❌ **DON'T**: Create additional validation layers - - Rationale: Reduces cognitive load, enables rapid execution, creates baseline for improvement - -3. **Focus on Current Phase Only**: - - Trust that design is complete and correct - - Focus effort on implementation success criteria - - Only revisit previous phase if explicit bug found - - Success indicator: Steady forward progress without re-work - -### Step 3: Apply Four-Level Completion Framework - -Systematic completion at Phase, Task, Epic, and Milestone levels. - -1. **Level 1: Phase Completion**: - - **Trigger**: All Success Criteria (Success Criteria) within phase complete - - **Required Actions**: - - Update issue body checkboxes: Mark all Success Criteria as `- [x]` - - Add phase completion comment with evidence summary - - Optional: Work log entry for strategic insights - - **Example**: - ```markdown - ## Implementation Phase Complete - Routing Service Implementation - - **Evidence Summary**: - - ✅ Implementation.SC01: Pattern matching engine implemented (commit 7a3d8f2) - - ✅ Implementation.SC02: Instruction file parsing working (commit b4e91c5) - - ✅ Implementation.SC03: Confidence scoring functional (commit c2d4e6f) - - **Implementation Highlights**: - - Used glob patterns for applies_to matching - - Confidence scoring based on context keyword matching + priority weighting - - Returns top 3 matches with rationale - ``` - - Expected outcome: Clear evidence phase objectives met - -2. **Level 2: Task Completion**: - - **Trigger**: ALL Acceptance Criteria (Acceptance Criteria) AND Completion Validation (Completion Validation) complete - - **Required Actions**: - - Verify ALL Acceptance Criteria marked complete - - Verify ALL Completion Validation marked complete - - Add task completion comment with summary - - Work log entry documenting outcomes - - Close issue with "Closes #X" in final commit - - **Completion Validation (Completion Validation) Requirements**: - - [ ] All code changes committed and pushed - - [ ] All tests passing (100% deterministic pass rate) - - [ ] Documentation updated - - [ ] No breaking changes introduced - - [ ] Integration validated with dependent services - - **Example**: - ```markdown - ## Task Complete - Routing Service Pattern Matching - - **All Acceptance Criteria Met**: - - ✅ Design.AC01: Pattern matching functional - - ✅ Implementation.AC01: Integration with knowledge system - - ✅ Validation.AC01: Error handling implemented - - **All Completion Validation Passed**: - - ✅ Completion.CV01: All tests passing (247/247) - - ✅ Completion.CV02: Documentation updated (API docs, README) - - ✅ Completion.CV03: Integration test with audit service passing - - Closes #42 - ``` - - Integration point: Maps to trust-based phase execution completion gates - -3. **Level 3: Epic Completion**: - - **Trigger**: ALL Epic tasks complete (Epic Task X/X) - - **Required Actions**: - - Verify all Epic tasks closed (Task 1/4 through Task 4/4) - - Add Epic completion comment summarizing progression - - Work log entry with Epic outcomes and learnings - - Close Epic issue - - **Example**: - ```markdown - ## Epic Complete - [Epic]-routing_service - - **All Tasks Completed**: - - ✅ [Task]-pattern_matching_engine (#42) - - ✅ [Task]-confidence_scoring (#45) - - ✅ [Task]-knowledge_system_integration (#48) - - ✅ [Task]-performance_optimization (#51) - - **Epic Outcomes**: - - Routing service functional and integrated - - Average routing time: 12ms (target: <50ms) - - Confidence accuracy: 94% on test suite - - **Key Learnings**: - - Glob pattern matching faster than regex for applies_to - - Caching instruction file metadata critical for performance - - Need versioning strategy for breaking instruction format changes - ``` - - Success indicator: Complete Epic delivered, learnings captured - -4. **Level 4: Milestone Completion**: - - **Trigger**: ALL Tasks/Epics in milestone complete - - **Required Actions**: - - Verify all milestone issues closed - - Create milestone retrospective document - - Comprehensive work log entry - - Close milestone with strategic summary - - **Example**: - ```markdown - ## Milestone Complete - Project Foundation (v0.1) - - **Scope Delivered**: - - ✅ [Epic]-routing_service - Agent context matching - - ✅ [Epic]-audit_service - Event capture & storage - - ✅ [Task]-docker_compose_configuration - - ✅ [Task]-typescript_service_standards - - **Strategic Outcomes**: - - Core agent infrastructure operational - - Foundation for bounded autonomy established - - Knowledge routing enables context-aware agent behavior - - **Retrospective Highlights**: - - Time-free scoping worked well, no deadline pressure - - Deterministic validation prevented agent confusion - - Need better cross-service testing strategy for v0.2 - ``` - - Expected outcome: Milestone value delivered, organizational learning captured - -### Step 4: Validate Against Quality Gates - -Ensure work meets completion criteria before marking complete. - -1. **Phase Level Quality Gates**: - - [ ] All Success Criteria items completed - - [ ] Phase completion comment added with evidence - - [ ] Evidence artifacts documented (commits, files, etc.) - - [ ] No open questions or unresolved issues in phase scope - - Expected outcome: Phase demonstrably complete - -2. **Task Level Quality Gates**: - - [ ] All Acceptance Criteria items completed - - [ ] All Completion Validation items completed - - [ ] All tests passing (deterministic validation) - - [ ] Documentation updated (code docs, user docs, architecture docs) - - [ ] Work log entry created - - [ ] No breaking changes or regressions introduced - - Success indicator: Task fully implemented, tested, and documented - -3. **Epic Level Quality Gates**: - - [ ] All Epic tasks (1/X through X/X) completed - - [ ] Epic success criteria met (from Epic description) - - [ ] Epic outcomes documented - - [ ] Lessons learned captured - - [ ] Cross-cutting concerns addressed (security, performance, observability) - - Integration point: Epic validation ensures comprehensive feature delivery - -4. **Milestone Level Quality Gates**: - - [ ] All milestone issues closed - - [ ] Milestone objectives achieved - - [ ] Retrospective completed - - [ ] Strategic learnings documented - - [ ] Foundation prepared for next milestone - - Expected outcome: Major capability increment delivered - -### Step 5: Document Completion with Evidence - -Provide concrete evidence of completion, not just assertions. - -1. **Evidence Summary Format**: - ```markdown - **Evidence Summary**: - - ✅ SC01: [What was completed] ([specific evidence: commit, file, test]) - - ✅ SC02: [What was completed] ([specific evidence]) - - ✅ SC03: [What was completed] ([specific evidence]) - ``` - - Rationale: Enables verification and learning capture - -2. **Link Artifacts**: - - Commit SHAs for code changes - - File paths for created/modified files - - Test results for validation - - Deployment logs for operational changes - - Success indicator: Any reviewer can verify completion independently - -3. **Highlight Key Decisions**: - - Implementation approach chosen and why - - Trade-offs made - - Technical debt incurred (with rationale) - - Expected outcome: Future maintainers understand context - -## Examples - -### Example 1: Phase Completion for Routing Service - -**Context**: Completing Implementation Phase (Implementation) for routing service pattern matching - -**Scenario**: All implementation Success Criteria met, ready to mark phase complete - -```markdown -## Implementation Phase Complete - Pattern Matching Implementation - -**Evidence Summary**: - -- ✅ Implementation.SC01: Glob pattern matching implemented - - File: `src/services/routing/pattern-matcher.ts` - - Commit: 7a3d8f2 - - Test coverage: 24 tests passing - -- ✅ Implementation.SC02: Confidence scoring algorithm implemented - - File: `src/services/routing/confidence-scorer.ts` - - Commit: b4e91c5 - - Test coverage: 18 tests passing - -- ✅ Implementation.SC03: Error handling for missing files implemented - - File: `src/services/routing/error-handler.ts` - - Commit: c2d4e6f - - Test coverage: 12 tests passing - -**Implementation Highlights**: - -- Chose glob over regex for 3x performance improvement -- Confidence scoring uses weighted factors: context match (40%), priority (30%), domain match (30%) -- Graceful degradation returns template when no matches found - -**Next Phase**: validation - Integration Testing -``` - -**Expected Result**: Clear evidence phase is complete, foundation established for next phase - -### Example 2: Task Completion for Audit Service - -**Context**: Completing entire task for audit event logging implementation - -**Scenario**: All phases complete, all acceptance criteria met, all completion validation passed - -```markdown -## Task Complete - Audit Event Logging Implementation - -**All Phases Complete**: -- ✅ Design Phase: Requirements & Design -- ✅ Implementation Phase: Implementation -- ✅ Validation Phase: Testing & Validation -- ✅ Completion Phase: Documentation - -**All Acceptance Criteria Met**: -- ✅ Design.AC01: Event schema designed and documented -- ✅ Implementation.AC01: Event capture service implemented -- ✅ Implementation.AC02: Event storage (PostgreSQL) integrated -- ✅ Validation.AC01: Unit tests passing (156/156) -- ✅ Validation.AC02: Integration tests passing (42/42) - -**All Completion Validation Passed**: -- ✅ Completion.CV01: All code committed (commits 3a2b1c through 9d8e7f) -- ✅ Completion.CV02: All tests passing deterministically (10 consecutive runs) -- ✅ Completion.CV03: API documentation updated (docs/api/audit-service.md) -- ✅ Completion.CV04: Integration with routing service validated - -**Key Metrics**: -- Event capture latency: avg 3ms, p99 8ms -- Storage reliability: 100% (no lost events in testing) -- API response time: avg 12ms - -Closes #45 -``` - -**Expected Result**: Task fully complete, all quality gates passed, ready for production - -**Trade-offs**: More documentation overhead, but provides complete verification trail - -### Example 3: Trusting Previous Phase Outputs - -**Context**: Starting Validation Phase (Testing) after Implementation Phase (Implementation) is complete - -**Scenario**: Agent reads implementation outputs and proceeds with testing without re-analyzing implementation decisions - -```markdown -## Starting Validation Phase - Testing & Validation - -**Reading Implementation Phase Outputs** (marked complete): - -From implementation completion comment: -- Implementation: Pattern matching using glob library -- Confidence scoring: 3-factor weighted algorithm -- Error handling: Graceful degradation to template - -**Proceeding with Testing** (trusting implementation decisions): - -Validation.SC01: Create test suite for pattern matching -- Test glob patterns match expected files ✓ -- Test edge cases (no matches, multiple matches) ✓ -- Test performance (target: <50ms per route) ✓ - -Validation.SC02: Validate confidence scoring -- Test known contexts produce expected scores ✓ -- Test score ordering (higher confidence first) ✓ -- Test boundary conditions (0.0 to 1.0 range) ✓ - -**NOT re-analyzing**: -- ✗ Should we use regex instead of glob? (implementation decision, trust it) -- ✗ Should confidence algorithm be different? (implementation decision, trust it) -- ✗ Should error handling be different? (implementation decision, trust it) - -**Focus**: Test what was implemented in implementation, validate it works per its design -``` - -**Expected Result**: Rapid progress on validation without re-work, implementation decisions trusted as foundational truth - -## Validation Checklist - -Complete before marking any level as done: - -### Phase Completion -- [ ] All Success Criteria items have `- [x]` checkboxes -- [ ] Phase completion comment added with evidence summary -- [ ] Evidence artifacts linked (commits, files, tests) -- [ ] No unresolved issues within phase scope -- [ ] Implementation highlights documented - -### Task Completion -- [ ] All phases marked complete -- [ ] All Acceptance Criteria items have `- [x]` checkboxes -- [ ] All Completion Validation items have `- [x]` checkboxes -- [ ] All tests passing (deterministic 100% pass rate) -- [ ] Documentation updated (code, API, user, architecture) -- [ ] Work log entry created with outcomes -- [ ] Issue closed with "Closes #X" in commit - -### Epic Completion -- [ ] All Epic tasks (1/X through X/X) closed -- [ ] Epic success criteria met (from Epic description) -- [ ] Epic completion comment with progression summary -- [ ] Work log entry with Epic outcomes and learnings -- [ ] Cross-cutting concerns validated (security, performance, etc.) -- [ ] Epic issue closed - -### Milestone Completion -- [ ] All milestone issues closed -- [ ] Milestone objectives achieved -- [ ] Retrospective document created -- [ ] Comprehensive work log entry -- [ ] Strategic learnings documented -- [ ] Milestone closed with strategic summary - -## Common Pitfalls - -### Pitfall 1: Partial Context Reading - -- ❌ **Problem**: Using head/tail/truncation to "quickly check" files during development -- **Why it happens**: Perceived time savings, but creates knowledge gaps -- ✅ **Solution**: Always read complete files or use proper pagination -- **Example**: Reading only first 100 lines of instruction file misses critical edge cases documented later - -### Pitfall 2: Re-Validating Completed Phases - -- ❌ **Problem**: Re-analyzing work that already passed Success Criteria/AC##/CV## -- **Why it happens**: Lack of trust in previous phase outputs -- ✅ **Solution**: Trust validated outputs, focus on current phase criteria -- **Example**: Re-debating architecture decisions during testing phase instead of testing the implemented architecture - -### Pitfall 3: Premature Completion - -- ❌ **Problem**: Marking phase/task complete before all criteria met -- **Why it happens**: Pressure to show progress, incomplete understanding of criteria -- ✅ **Solution**: Verify all checkboxes before declaring complete, use quality gate checklist -- **Example**: Marking Implementation.SC03 complete when error handling only covers 2/5 error cases - -### Pitfall 4: Missing Documentation - -- ❌ **Problem**: Completing work without work log entries or completion comments -- **Why it happens**: Focus on implementation, documentation feels like overhead -- ✅ **Solution**: Document evidence and outcomes at each level - enables learning -- **Example**: Closing task without documenting key implementation decisions and trade-offs - -### Pitfall 5: Incomplete Evidence - -- ❌ **Problem**: Completion comment says "done" without linking artifacts -- **Why it happens**: Treating completion as assertion rather than verification -- ✅ **Solution**: Link specific commits, files, tests, metrics as evidence -- **Example**: "Implementation.SC01 complete" vs "Implementation.SC01 complete (commit 7a3d8f2, file pattern-matcher.ts, 24 tests passing)" - -## Edge Cases - -### Edge Case 1: Discovering Issues in Previous Phase - -**When**: During validation (Testing), discover bug in implementation (Implementation) - -**Approach**: -- Document the bug clearly (what, where, impact) -- Fix the bug in current phase if minor -- If major architectural issue, create new task for proper fix -- Update implementation completion comment noting bug found and fixed -- Don't re-open phase unless fundamentally incomplete - -**Example**: During testing, discover pattern matching doesn't handle negation patterns. Add negation support as validation work, document in implementation note. - -### Edge Case 2: Scope Expansion Mid-Phase - -**When**: While working on Implementation.SC02, realize additional work needed - -**Approach**: -- Evaluate if new work fits current Success Criteria -- If yes: Update SC description to reflect expanded scope -- If no: Create new SC (Implementation.SC04) or defer to future task -- Document scope expansion in phase notes -- Update estimates if relevant (for time-free scoping: complexity) - -**Example**: Implementation.SC02 "Implement confidence scoring" expands to include caching layer for performance. Update SC02 to include caching. - -### Edge Case 3: Blocked Phase Completion - -**When**: Implementation.SC03 blocked by external dependency (API not ready) - -**Approach**: -- Document blocker clearly in phase notes -- Mark SC03 as blocked (not complete) -- Continue with non-blocked work (Validation.SC01 if independent) -- Update issue with blocker status and resolution plan -- Don't mark phase complete until blocker resolved - -**Example**: Implementation.SC03 requires GitHub MCP integration, but MCP server not deployed. Document blocker, work on other SCs, resolve blocker, complete SC03, then complete phase. - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| Confusion about what's complete | Unclear evidence or missing completion comments | Add evidence summary with specific artifacts linked | -| Re-work on validated phases | Not trusting previous phase outputs | Document in phase notes "design validated, trusting outputs", focus on current phase | -| Premature completion claims | Misunderstanding completion criteria | Review quality gate checklist before marking complete | -| Missing learnings | No work log entries or completion summaries | Make completion comment mandatory, include implementation highlights | -| Incomplete validation | Only some CV items checked | Require ALL Completion Validation items checked before task can close | -| Progress stalls | Reading incomplete context | Always read complete files/issues before making decisions | - -## Related Instructions - -- **See also**: [trust_based_task_execution.instructions.md](./trust_based_task_execution.instructions.md) - Complete Success Criteria/AC##/CV## framework this workflow builds on -- **Prerequisites**: [feature_development.instructions.md](./feature_development.instructions.md) - How features map to phases and tasks -- **See also**: [task_creation_workflow.instructions.md](../project_management/task_creation_workflow.instructions.md) - Creating properly structured tasks this workflow completes -- **See also**: [deterministic_validation_framework.instructions.md](../validation/deterministic_validation_framework.instructions.md) - Validation standards for Completion Validation completion -- **See also**: Project Glossary - Authoritative source for PM terminology (Epic, Task, Sub-Task, Sub-Issue, Milestone) -- **See also**: [Glossary Maintenance](../project_management/glossary_maintenance.instructions.md) - Keeping glossary current and complete - ---- - -**Success Criteria**: All development work maintains complete context, trusts validated phases, follows four-level completion framework with evidence-based progress tracking, and meets quality gates at each level. - -**Confidence Check**: Are you reading complete files or using partial reads? Do you trust previous phase outputs or re-analyze them? Is completion backed by evidence or just assertions? diff --git a/.pongogo/instructions/trust_execution/feature_development.instructions.md b/.pongogo/instructions/trust_execution/feature_development.instructions.md deleted file mode 100644 index 81059294..00000000 --- a/.pongogo/instructions/trust_execution/feature_development.instructions.md +++ /dev/null @@ -1,458 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Feature Development Standards" -description: "Feature development standards including design-first approach and quality gates." -applies_to: - - "**/*" -domains: - - "trust_execution" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 0 - triggers: - keywords: - - feature_development - - SC_AC_CV - - success_criteria - - acceptance_criteria - - completion_validation - - autonomy_ladder - - phase_completion - - propose_patch_apply - - quality_gates - - trust_execution - nlp: "Phase-based feature development with SC/AC/CV validation gates implementing autonomy ladder (propose→patch→apply) and trust-based execution" -evaluation: - success_signals: - - SC items completed with evidence before AC validation - - AC items verified after all SC complete - - CV requires all AC across entire task - - Phase completion includes checkbox + comment + work log - - Autonomy level matches complexity assessment - failure_signals: - - AC checked before all SC complete - - CV checked with pending AC items - - Evidence missing for checked items - - Phase marked complete without reporting deliverables - - Re-analyzing trusted previous phase outputs ---- - - -# Feature Development Standards - -**Purpose**: Define phase-based feature development lifecycle with SC/AC/CV validation gates implementing autonomy ladder. - -**Philosophy**: Quality gates at each development stage ensure systematic validation without requiring post-completion re-verification. - ---- - -## When to Apply - -Use phase-based feature development when: - -- Implementing new features or significant changes -- Working through multi-phase work items -- Validating work before phase progression -- Determining appropriate agent autonomy levels -- Coordinating work across feature team agents - ---- - -## Quick Reference - -**SC → AC → CV Workflow Patterns**: - -**1. Phase Item Types** (Sequential Execution): -``` -Phase P##: -├─ Working Memory (WM) - Narrative context, no checkboxes -├─ Implementation Priorities (IP) - Ordering decisions, no checkboxes -├─ Success Criteria (SC) - Deliverables, checkboxes with evidence -│ └─ Complete ALL SC before proceeding to AC -├─ Acceptance Criteria (AC) - Quality validation, checkboxes after SC -│ └─ Complete ALL AC before proceeding to CV -└─ Completion Validation (CV) - Operational readiness, checkboxes after AC - └─ CV requires ALL AC across ENTIRE task (not just current phase) -``` - -**2. Success Criteria (SC) Execution**: -```markdown -- [ ] Design.SC01: [Deliverable description] -- [ ] Design.SC02: [Deliverable description] - -Workflow: -1. Implement deliverable -2. Capture evidence (commit SHA, file path, test result) -3. Update checkbox: - [x] Design.SC01 -4. Add comment if approach differs from plan -``` - -**3. Acceptance Criteria (AC) Execution**: -```markdown -Wait until ALL SC items checked ✓ - -- [ ] Design.AC01: [End-to-end validation] -- [ ] Design.AC02: [Quality check] - -Workflow: -1. Verify all Design.SC## checked -2. Perform end-to-end validation -3. Document results in issue comment -4. Update checkboxes only if validation passes -5. Create work log entry -``` - -**4. Completion Validation (CV) Execution**: -```markdown -Wait until ALL AC items across ENTIRE task checked ✓ - -- [ ] Completion.01: All code committed and pushed -- [ ] Completion.02: All tests passing (100% deterministic) -- [ ] Completion.03: Documentation updated -- [ ] Completion.04: No breaking changes -- [ ] Completion.05: Integration validated with dependent services - -Workflow: -1. Verify ALL Acceptance Criteria across entire task checked -2. Perform operational validation -3. Document concrete evidence (logs, test results) -4. Update CV checkboxes -5. Create work log entry -``` - -**5. Autonomy Ladder Mapping** (SC → AC → CV = Propose → Patch → Apply): -- **Simple Complexity**: Apply autonomy → Post-application review -- **Moderate Complexity**: Patch autonomy → Pre-merge approval -- **Complex Complexity**: Propose autonomy → Architecture approval before implementation - -**6. Phase Completion Workflow**: -```bash -# 1. Update issue body checkboxes -- [x] Design.SC01, Design.SC02, Design.SC03 - -# 2. Add phase completion comment -"## Design Phase Complete -Evidence Summary: -- ✅ Design.SC01: [what] (commit abc123) -- ✅ Design.SC02: [what] (commit def456)" - -# 3. Optional: Work log entry for strategic insights -``` - -**7. Common Sequential Violations** (AVOID): -- ❌ Checking AC before all SC complete → Premature validation -- ❌ Checking CV before all AC complete → Skipping quality gates -- ❌ Checking CV with AC items pending in other phases → Incomplete task validation -- ✅ **ALWAYS**: Complete SC → then AC → then CV sequentially - ---- - -## Core Principles - -- **Trust Completed Phases**: Phases with all SC/AC/CV items checked are trustworthy, implement without re-analysis -- **Phase Validation Gates**: SC (deliverables) � AC (quality) � CV (operational) provide systematic validation -- **Sequential Execution**: Complete SC items before AC, complete all AC before CV -- **Evidence Required**: Every checked item must have evidence (commit, PR, test result, work log) -- **Autonomy Ladder Mapping**: SC�AC�CV gates map to propose�patch�apply autonomy levels - -## Step-by-Step Guidance - -### 1. **Understand Phase Structure** - - Working Memory (WM): Strategic context and prerequisites (narrative prose, no checkboxes) - - Implementation Priorities (IP): Execution ordering decisions (narrative prose, no checkboxes) - - Success Criteria (SC): Deliverable implementation milestones (checkboxes with evidence) - - Acceptance Criteria (AC): End-to-end quality validation (checkboxes after all SC complete) - - Completion Validation (CV): Operational readiness verification (checkboxes after all AC complete) - - Validation Tasks (V): Optional quality checks (excluded from completion calculation) - - Expected outcome: Clear understanding of phase item types and sequencing - -### 2. **Execute Success Criteria Items** - - Implement deliverable described in SC item - - Capture evidence immediately (commit, PR, or work log entry) - - Update checkbox from `- [ ]` to `- [x]` - - Add comment if approach differs from plan - - Expected outcome: Deliverables complete with evidence - -### 3. **Execute Acceptance Criteria Items** - - Verify all SC items checked before starting AC validation - - Perform end-to-end validation from user perspective - - Document validation results in issue comment - - Update AC checkboxes only if validation passes - - Create work log entry documenting validation - - Expected outcome: Quality validated across complete phase - -### 4. **Execute Completion Validation Items** - - Verify all AC items across ENTIRE task checked (not just current phase) - - Perform operational validation with concrete evidence - - Document operational readiness (logs, test results, deployment verification) - - Update CV checkboxes with evidence - - Create work log entry for operational validation - - Expected outcome: Operational readiness verified and documented - -### 5. **Complete Phase Reporting** - - Update issue body checkboxes (single source of truth) - - Add phase completion comment (evidence, validation outcomes, artifacts) - - Create work log entry (phase identifier, outcomes, follow-ups) - - Expected outcome: All three reporting deliverables complete - -## Examples - -### Example 1: API Endpoint Development - -Context: Adding new endpoint following SC�AC�CV gates (propose�patch�apply) - -```markdown -## Design Phase: Implementation (Simple Complexity � Apply Autonomy) - -### Success Criteria (Deliverable Implementation) -- [ ] Design.SC01: GET /api/instructions endpoint created -- [ ] Design.SC02: File path glob matching implemented -- [ ] Design.SC03: Response formatting with instruction metadata - -### Workflow: -1. Implement SC01: Create endpoint handler - - Evidence: Commit abc123 "Add GET /api/instructions endpoint" - - Update: - [x] Design.SC01 - -2. Implement SC02: Add glob matching logic - - Evidence: Commit def456 "Implement file path glob matching" - - Update: - [x] Design.SC02 - -3. Implement SC03: Format response - - Evidence: Commit ghi789 "Add instruction metadata to response" - - Update: - [x] Design.SC03 - -### Acceptance Criteria (End-to-End Quality) -Wait until ALL SC items checked - -- [ ] Design.AC01: Endpoint returns correct instructions for valid paths -- [ ] Design.AC02: Invalid paths return appropriate error responses - -### Workflow: -1. Verify all SC complete: Design.SC01, Design.SC02, Design.SC03 -2. Test end-to-end: - - Valid path � instructions returned - - Invalid path � 404 error -3. Document in issue comment: - - Test scenarios executed - - Validation outcomes - - Edge cases verified -4. Update: - [x] Design.AC01, - [x] Design.AC02 -5. Work log entry: "design validation complete, all AC criteria met" -``` - -**Context**: Simple endpoint following established patterns (Apply autonomy level) -**Expected Result**: Systematic validation through SC�AC gates, evidence captured - -### Example 2: Sequential Execution Preventing Premature Checking - -Context: Avoiding common workflow mistakes - -```markdown -## L WRONG: Checking AC Before SC Complete - -Implementation Phase: -- [x] Implementation.SC01: Authentication middleware implemented -- [ ] Implementation.SC02: Password hashing integrated (STILL IN PROGRESS) -- [x] Implementation.AC01: Users can authenticate � PREMATURE! SC02 not done - -Problem: -- AC validation requires all deliverables (SC items) -- Checking AC before SC complete breaks sequential workflow -- Cannot validate end-to-end when deliverables incomplete - -## CORRECT: Sequential SC � AC Execution - -Implementation Phase: -- [x] Implementation.SC01: Authentication middleware (commit abc123) -- [x] Implementation.SC02: Password hashing (commit def456) -- [x] Implementation.AC01: Authentication validated (comment with test results) - -Workflow: -1. Complete ALL SC items first -2. Capture evidence for each SC -3. THEN perform AC validation -4. Document AC validation in comment -5. Check AC boxes only after validation passes -``` - -**Context**: Enforcing sequential workflow for systematic validation -**Expected Result**: Proper sequencing ensures quality gates work correctly - -### Example 3: Autonomy Ladder Mapping - -Context: Different complexity levels map to different autonomy and approval gates - -```markdown -## Simple Complexity � Apply (Bounded Autonomy) -**Task**: Add standard CRUD endpoint - -SC (Propose Design): -- Endpoint follows REST conventions -- Standard error handling -- Existing auth middleware - -AC (Patch Implementation): -- Integration tests pass -- API documentation updated -- Error responses validated - -CV (Apply with Post-Review): -- Deployed to staging -- Smoke tests pass -- Post-apply review scheduled - -**Approval**: Post-application review (agent can apply directly) - ---- - -## Moderate Complexity � Patch (Supervised Autonomy) -**Task**: Implement instruction routing service - -SC (Propose Design): -- Glob matching algorithm -- Caching strategy -- Performance requirements - -AC (Patch Implementation): -- Pattern matching tested -- Cache invalidation works -- Performance benchmarks met - -CV (Pre-Apply Approval): -- Integration tests complete -- Documentation comprehensive -- Pre-merge review approval required - -**Approval**: Technical review before merge (supervised implementation) - ---- - -## Complex Complexity � Propose (Design Autonomy) -**Task**: Design autonomy ladder architecture - -SC (Propose Design): -- Approval gate mechanisms -- Rollback strategies -- Security model - -AC (Design Validation): -- Architecture review approved -- Security implications assessed -- Rollback procedures tested - -CV (Architecture Approval): -- Design document complete -- Stakeholder approval -- Implementation plan validated - -**Approval**: Architecture review before implementation (design only, human implements) -``` - -**Context**: Autonomy ladder with graduated trust levels -**Expected Result**: Appropriate approval gates for complexity and risk - -## Validation Checklist - -Before marking phase complete: - -- [ ] All SC items checked with evidence (commits, PRs, work log) -- [ ] All AC items checked with validation documentation -- [ ] CV items checked if final phase (operational validation documented) -- [ ] Phase completion comment added to issue -- [ ] Work log entry created -- [ ] No premature checking (SC before AC before CV) -- [ ] Trust-based execution followed (no re-analysis of previous phases) - -## Common Pitfalls - -### Pitfall 1: Checking Items Without Evidence - -- L **Problem**: Checking SC/AC/CV boxes without commits, tests, or documentation -- **Why it happens**: Treating checkboxes as to-do list instead of evidence tracking -- **Solution**: Capture evidence BEFORE checking box (commit first, then check) -- **Example**: Empty checkbox check � Commit abc123, THEN check box - -### Pitfall 2: Premature AC Validation - -- L **Problem**: Checking AC items before all SC items complete -- **Why it happens**: Not understanding sequential workflow requirement -- **Solution**: Complete ALL SC items first, THEN perform AC validation -- **Example**: 2/3 SC complete but AC checked � Finish SC03, THEN validate AC - -### Pitfall 3: Skipping Phase Completion Reporting - -- L **Problem**: Marking phase complete without issue comment and work log entry -- **Why it happens**: Focus on implementation, documentation feels like overhead -- **Solution**: All three required: checkbox update + comment + work log -- **Example**: Only checkbox updated � Add completion comment + work log entry - -### Pitfall 4: CV Items Before All AC Complete - -- L **Problem**: Checking CV items when AC items in other phases still pending -- **Why it happens**: Misunderstanding CV applies to entire task, not just final phase -- **Solution**: CV requires ALL AC across ALL phases complete -- **Example**: Validation.AC incomplete but Completion. checked � Complete Validation.AC first - -## Edge Cases - -### Edge Case 1: Discovery of Missing SC Items During Implementation - -**When**: Implementation reveals necessary deliverable not in original SC list -**Approach**: -- Add new SC item to phase with clear description -- Mark as discovered during implementation -- Capture evidence and check when complete -- Document in phase completion comment -- Update templates if pattern emerges - -**Example**: implementation implementation reveals logging needed � Add Implementation.SC04: Request logging integrated, implement, document discovery - -### Edge Case 2: AC Validation Fails - -**When**: End-to-end validation reveals quality issues -**Approach**: -- Do NOT check AC item -- Document validation failure in comment -- Identify root cause (which SC item has issue) -- Fix implementation, re-validate -- Only check AC when validation passes - -**Example**: Implementation.AC01 fails (auth returns wrong token) � Debug Implementation.SC02 (token generation), fix, re-validate, then check AC - -### Edge Case 3: Cross-Agent Phase Handoffs - -**When**: One agent completes phase, another continues -**Approach**: -- First agent completes all phase reporting (checkbox + comment + work log) -- Second agent reads phase outputs, trusts completion -- Second agent implements next phase per previous phase recommendations -- Handoff documented in both agents' work logs -- No re-validation of previous agent's work - -**Example**: PM agent completes analysis analysis � Engineer agent reads analysis outputs, trusts analysis, implements design per analysis recommendations - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| AC checked but SC incomplete | Sequential workflow violated | Complete all SC first, then re-validate AC | -| No evidence for checked items | Evidence capture skipped | Add commits/PRs/comments, update issue with evidence | -| CV checked but AC pending | Misunderstanding CV scope | CV requires ALL AC complete across entire task | -| Phase marked complete without report | Reporting requirements skipped | Add completion comment + work log entry | -| Re-analyzing previous phase | Trust principles violated | Read phase outputs, trust, implement directly | - -## Related Instructions - -- **See also**: [trust_based_task_execution.instructions.md](./trust_based_task_execution.instructions.md) - Trust framework ensuring phase outputs are trustworthy -- **Prerequisites**: [time_free_project_management.instructions.md](../project_management/time_free_project_management.instructions.md) - Complexity-based sizing guiding autonomy levels -- **Next steps**: [development_workflow_essentials.instructions.md](./development_workflow_essentials.instructions.md) - Additional workflow patterns for complete development lifecycle - ---- - -**Success Criteria**: Features developed through systematic phase progression with SC�AC�CV validation gates, evidence captured for all items, appropriate autonomy levels applied, and trust-based execution followed. - -**Confidence Check**: Are SC items complete before AC validation? Is evidence captured for every checked item? Are phases trusted without re-analysis? Does complexity determine autonomy level? diff --git a/.pongogo/instructions/trust_execution/trust_based_task_execution.instructions.md b/.pongogo/instructions/trust_execution/trust_based_task_execution.instructions.md deleted file mode 100644 index da5f3d7e..00000000 --- a/.pongogo/instructions/trust_execution/trust_based_task_execution.instructions.md +++ /dev/null @@ -1,396 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Trust-Based Task Execution" -description: "Trust-based task execution framework for bounded autonomous work with approval paths." -applies_to: - - "**/*" -domains: - - "trust_execution" -priority: "P2" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 0 - triggers: - keywords: - - trust_execution - - trust_based - - prerequisite_work - - acceptance_criteria - - success_indicators - - completed_work - - trust_protocol - - re-analysis - - meta-system_improvement - - task_validation - nlp: "Trust framework ensuring agents trust completed prerequisite work, leverage validation safeguards without re-analysis, and improve meta-system forward" -evaluation: - success_signals: - - Prerequisite work trusted without re-analysis - - Verification checklist completed before proceeding - - Implementation follows recommendations directly - - Learnings captured for meta-system improvement - failure_signals: - - Re-analyzing completed work unnecessarily - - Starting dependent work with incomplete prerequisites - - Proposing alternative approaches instead of implementing recommendations - - Questioning past work instead of improving forward ---- - - -# Trust-Based Task Execution - -**Purpose**: Establish trust framework ensuring agents trust completed prerequisite work (Tasks/Sub-Tasks) and leverage validation safeguards (Acceptance Criteria, Success Indicators) without re-analysis. - -**Philosophy**: Completed work is trustworthy through systematic validation during execution (via Acceptance Criteria checkboxes), not after completion. - ---- - -## When to Apply - -Use trust-based task execution when: - -- Starting any new Task or Sub-Task that depends on completed prerequisite work -- Implementing recommendations from completed analysis or design work -- Validating current work against previous Task/Sub-Task outputs -- Designing meta-system improvement processes -- Coordinating work across multiple agents in feature team - ---- - -## Quick Reference - -**Key Trust Decision Criteria**: - -**1. Is Prerequisite Work Trustworthy?** (Verification Checklist): -- [ ] All Acceptance Criteria checkboxes completed -- [ ] Success Indicators achieved -- [ ] Task/Sub-Task marked as complete with closing comment -- [ ] Work log entry documents completion -- [ ] Deliverables accessible and readable (docs, commits, artifacts) - -**If ALL checked**: ✅ TRUST THE WORK → Proceed with dependent task -**If ANY missing**: ⚠️ COMPLETE PREREQUISITE WORK FIRST → Don't start current task - -**2. Trust vs Re-Analysis Decision Tree**: -``` -Starting dependent work? -├─ Prerequisite complete (all checkboxes)? NO → Complete prerequisites first -├─ Prerequisite complete? YES - ├─ Do you understand the outputs? NO → Read carefully, ask for clarification - ├─ Do you understand the outputs? YES - ├─ Do outputs seem "unclear"? → Re-read for comprehension, TRUST when clarified - └─ Outputs clear? → ✅ TRUST outputs, implement directly -``` - -**3. When to TRUST (Proceed Directly)**: -- ✅ Prerequisite work has all Acceptance Criteria checked -- ✅ Task closing comment provides evidence of completion -- ✅ Recommendations/outputs are explicit and actionable -- ✅ You understand what to implement -- **Action**: Read outputs, implement per recommendations - -**4. When to QUESTION (Block Progress)**: -- ❌ Prerequisite work missing Acceptance Criteria checkboxes -- ❌ No closing comment or work log entry -- ❌ Deliverables not accessible -- ❌ Fundamental completion criteria not met -- **Action**: Return to prerequisite work, complete properly - -**5. Common Trust Anti-Patterns** (AVOID): -- ❌ "Let me verify the analysis before implementing..." → Re-analysis -- ❌ "Should we reconsider the approach from that Task?" → Undermining validated work -- ❌ "Building extra validation layer to cross-check completed work..." → Distrust of Acceptance Criteria gates -- ❌ "This seems unclear, let me re-analyze..." → Excuse for re-doing work - -**6. Meta-System Improvement vs Re-Validation**: -- ✅ **DO**: "Task met all criteria. Enhance Acceptance Criteria templates for future work based on this learning." -- ❌ **DON'T**: "Task wasn't really complete. Add more validation before marking work complete." -- **Principle**: Improve forward, don't doubt backward - -**7. Correction Signals During Execution** (NEW - Routing IMP-018): - -Trust applies to COMPLETED prerequisite work, not current execution. When users signal corrections during active work: - -**Correction Signals** (PAUSE immediately): -- "wait, hold on" - User has new information -- "that's not what I" - Expectation mismatch -- "sorry, actually" - User changing direction -- "you're skipping" - Missing something important - -**Correct Response**: -1. STOP current action -2. Acknowledge: "Let me pause here" -3. Clarify: "What should I do differently?" -4. Resume with corrected understanding - -**Why This Isn't Distrust**: -- Trusting completed work ≠ ignoring user feedback -- Correction signals are NEW information, not re-analysis -- Responding to corrections prevents friction - ---- - -## Core Principles - -- **Trust Is Built-In**: Acceptance Criteria and Success Indicators validate quality DURING work, not after completion -- **Linear Task Progression**: Dependent work trusts prerequisite Task/Sub-Task outputs without re-analysis -- **Built-In Safeguards**: Acceptance Criteria checkboxes eliminate need for re-validation -- **Cross-Session Trust**: Trust extends across sessions through verification efficiency protocols -- **Improvement Over Re-Validation**: Analyze to make future work better, not question past work validity - -## Step-by-Step Guidance - -### 1. **Verify Prerequisites Complete** - - Identify prerequisite work: Which Tasks/Sub-Tasks must complete before this work? - - Check completion status: Are all Acceptance Criteria checkboxes checked? - - Locate deliverables: Where are outputs (documents, commits, artifacts)? - - Confirm work log entry exists: Is completion documented? - - Expected outcome: Prerequisites validated, ready to proceed - -### 2. **Read and Trust Prerequisite Outputs** - - Read prerequisite outputs: Analysis documents, recommendations, requirements - - Trust the content: Do not question validity of completed work - - Extract actionable items: What does this work tell me to implement? - - Note dependencies: What relationships exist between recommendations? - - Expected outcome: Clear understanding of what to implement without re-analyzing - -### 3. **Implement Per Recommendations** - - Follow guidance directly: Implement as specified in prerequisite work - - Do not redesign: Resist proposing alternative approaches - - Document deviations: If implementation reveals issues, note as learning - - Maintain scope: Stay within boundaries defined by prerequisite work - - Expected outcome: High-fidelity execution matching prerequisite recommendations - -### 4. **Validate Current Work** - - Check Success Indicators: Are deliverables achieving intended outcomes? - - Verify Acceptance Criteria: Does implementation meet quality thresholds? - - Complete checkboxes: Mark criteria as met with evidence - - Do NOT re-validate prerequisite work: Trust their completion validation - - Expected outcome: Current work validated, prerequisite work remains trusted - -### 5. **Document Learnings for Improvement** - - Capture insights: What worked well? What could be better? - - Identify meta-system gaps: Where could processes improve? - - Document for retrospective: Feed into improvement cycle - - Avoid blame: Focus on system improvement, not past work validation - - Expected outcome: Learnings captured for meta-system enhancement - -## Examples - -**Note**: The following examples use old phase notation (analysis/implementation, Success Criteria/AC##/CV##) for illustration. When applying these patterns, substitute: -- "Analysis Task/implementation/testing" → "Prerequisite Task/Sub-Task" -- "Success Criteria" → "Success Indicators" -- "Acceptance Criteria" → "Acceptance Criteria" -- "Completion Validation" → "Acceptance Criteria" (validation merged into AC) -- "Phase completion" → "Task/Sub-Task completion" - -### Example 1: Routing Service Implementation - -Context: Implementing instruction routing service after analysis phase complete - -```markdown -## Analysis Task: Analysis (COMPLETE ) -- All SC/AC/CV items checked -- Analysis document: `/docs/routing-service-design.md` -- Recommendations: - 1. Use file path glob matching for instruction selection - 2. Implement LRU cache for routing decisions - 3. Load instructions on-demand, not at startup - -## Implementation Task: Implementation (STARTING) - -### L WRONG: Re-Analysis Approach -"Let me review the routing options again to see if glob matching is best..." -- Re-analyzing completed analysis work -- Questioning validated recommendations -- Wasting effort, showing distrust - -### CORRECT: Trust-Based Execution -1. Read analysis analysis document � recommendations clear -2. Trust glob matching recommendation � implement as specified -3. Trust LRU cache recommendation � integrate caching library -4. Trust on-demand loading � implement lazy loading pattern -5. Validate implementation implementation � tests pass, integration works -6. Document in work log � "implementation complete per analysis recommendations" - -Result: -- Rapid implementation without decision paralysis -- High fidelity to analysis design -- Learnings: LRU cache size needed tuning (meta-system improvement opportunity) -``` - -**Context**: Multi-phase feature development with autonomy ladder (SC�AC�CV = propose�patch�apply) -**Expected Result**: Trust enables efficient execution, deviations become learnings not failures - -### Example 2: Cross-Session Trust with Verification Efficiency - -Context: Feature spanning 3 days with architecture document - -```markdown -## Session 1: Analysis Phase -- Read architecture.md (verification count: 1) -- Extract: "Microservices with API gateway, event-driven messaging" -- Document in summary: "architecture.md verified - microservices pattern" - -## Session 2: Implementation Phase -- Summary states: "architecture.md verified 1x" -- Decision: TRUST summary, DO NOT re-read -- Rationale: No architecture changes, apply microservices patterns -- Implement: Create service following documented pattern - -## Session 3: Integration Testing -- Summary states: "architecture.md verified 1x - DO NOT re-verify" -- Decision: TRUST directive, proceed with testing -- Rationale: Verification efficiency protocol, avoid redundancy -- Test: Integration tests using microservices assumptions - -Result: -- Verification budget preserved (1x instead of 3x) -- Cognitive load reduced (no re-processing) -- Faster execution (trust replaces re-analysis) -``` - -**Context**: Trust extends across sessions using verification efficiency protocols -**Expected Result**: Cross-session trust reduces redundancy and cognitive overhead - -### Example 3: Meta-System Improvement Without Re-Validation - -Context: Post-completion test catches edge case - -```markdown -## Scenario: Automated Test Finds Gap - -### L WRONG Response: Question Completed Work -"Test caught issue, so implementation wasn't really complete. -Add more validation before marking phases complete." - -Problem: -- Questioning completed work that met all criteria -- Adding validation layers instead of improving criteria -- Backward-looking doubt vs forward-looking improvement - -### CORRECT Response: Improve Meta-System -"Test caught edge case not in implementation acceptance criteria. -implementation was complete per SC/AC/CV - now enhance the criteria." - -Actions: -1. implementation remains trusted (met all defined criteria) -2. Update AC templates (include edge case category) -3. Add pattern to instructions (document for future) -4. Retrospective entry (capture as improvement opportunity) - -Result: -- implementation completion status unchanged -- Meta-system enhanced for future work -- Pattern captured for institutional knowledge -- Learning preserved without blame -``` - -**Context**: Post-completion validation triggers improvement, not re-validation -**Expected Result**: Continuous improvement without eroding trust foundation - -## Validation Checklist - -Before trusting prerequisite work: - -- [ ] All Success Indicators achieved in prerequisite Task/Sub-Task -- [ ] All Acceptance Criteria checkboxes checked in prerequisite Task/Sub-Task -- [ ] Task/Sub-Task closing comment exists with evidence -- [ ] Work log entry documents completion -- [ ] Deliverables accessible and readable (docs, commits, artifacts) - -If ALL items met: TRUST THE WORK - proceed with dependent task - -If ANY items missing: � COMPLETE PREREQUISITE WORK FIRST - don't start current task - -## Common Pitfalls - -### Pitfall 1: Re-Analyzing Completed Phases - -- L **Problem**: Creating validation layers to re-check previous phase work -- **Why it happens**: Lack of confidence in SC/AC/CV validation gates -- **Solution**: Trust SC/AC/CV gates, read outputs, implement directly -- **Example**: "Let me verify analysis findings" � Read analysis outputs, trust recommendations, implement - -### Pitfall 2: Creating Additional Validation Layers - -- L **Problem**: Building extra safeguards when SC/AC/CV already exist -- **Why it happens**: Distrust of established meta-system safeguards -- **Solution**: Use existing gates, focus on current work not previous validation -- **Example**: "Build script to cross-check analysis" � Trust analysis, validate implementation implementation instead - -### Pitfall 3: Treating Clear Outputs as "Unclear" - -- L **Problem**: Questioning explicit recommendations from completed phases -- **Why it happens**: Excuse for re-analyzing completed work -- **Solution**: Read carefully, trust explicit guidance, implement per recommendation -- **Example**: "This seems unclear" � Re-read for comprehension, trust when clarified - -### Pitfall 4: Suggesting Alternative Approaches - -- L **Problem**: Proposing different strategies than previous phase recommended -- **Why it happens**: Undermining systematic planning work -- **Solution**: Implement per recommendation, document deviations as learnings -- **Example**: "Better approach than analysis" � Implement analysis approach, capture alternative as insight - -## Edge Cases - -### Edge Case 1: Previous Phase Genuinely Incomplete - -**When**: Prerequisite phase missing SC/AC/CV checkboxes or work log entry -**Approach**: -- Do NOT start current phase implementation -- Return to previous phase completion -- Validate previous phase properly -- Only proceed when all completion criteria met -- Document why phase was marked incomplete - -**Example**: analysis has 2/3 SC items checked � Complete analysis.SC03, validate, THEN start implementation - -### Edge Case 2: Implementation Reveals Design Gap - -**When**: Following analysis recommendations reveals unforeseen issue -**Approach**: -- Continue implementation where possible -- Document gap as learning, not failure -- Flag for meta-system improvement -- Do not blame analysis for incomplete analysis -- Update instructions with discovered pattern - -**Example**: analysis recommended caching but didn't specify eviction policy � Choose reasonable default, document as AC enhancement opportunity - -### Edge Case 3: Cross-Agent Phase Dependencies - -**When**: Multiple agents working on related phases -**Approach**: -- Each agent trusts other agents' completed phases -- Coordinate through shared work log and phase outputs -- Do not re-validate other agent's work -- Flag integration issues as coordination improvements -- Document handoff points clearly - -**Example**: PM agent completes analysis analysis, Engineer agent implements implementation � Engineer trusts PM's analysis, implements directly - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| Agent re-analyzing completed phase | Trust anti-pattern violation | Review trust principles, read outputs and implement directly | -| Multiple validation layers proposed | Distrust of SC/AC/CV gates | Use existing gates, focus resources on current work | -| Slow progress due to paralysis | Decision paralysis from distrust | Trust validated plans, execute faithfully to create learning baseline | -| Improvement focused on re-validation | Backward-looking doubt mindset | Shift to forward-looking improvement, enhance criteria for future work | -| Redundant cross-session verification | Verification efficiency not applied | Check verification count, trust documented state, apply efficiency protocols | - -## Related Instructions - -- **See also**: [feature_development.instructions.md](./feature_development.instructions.md) - SC/AC/CV gates creating trust foundation -- **Prerequisites**: [agentic_decision_making.instructions.md](../agentic_workflows/agentic_decision_making.instructions.md) - Context-first decision-making supporting trust-based execution -- **Next steps**: [development_workflow_essentials.instructions.md](./development_workflow_essentials.instructions.md) - Workflow patterns leveraging trust framework - ---- - -**Success Criteria**: Agents trust completed phase outputs, implement per recommendations without re-analysis, validate current work not previous phases, and feed learnings into meta-system improvement. - -**Confidence Check**: Are you reading previous phase outputs or re-analyzing them? Are you implementing per recommendations or redesigning? Are learnings captured for improvement or used to question past work? diff --git a/.pongogo/instructions/validation/deterministic_validation_framework.instructions.md b/.pongogo/instructions/validation/deterministic_validation_framework.instructions.md deleted file mode 100644 index bd1d4e77..00000000 --- a/.pongogo/instructions/validation/deterministic_validation_framework.instructions.md +++ /dev/null @@ -1,666 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Deterministic Validation Framework" -description: "Deterministic validation framework for consistent, reproducible verification results." -applies_to: - - "**/*" -domains: - - "validation" -priority: "P1" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 0 - triggers: - keywords: - - deterministic_validation - - 100%_pass_rate - - flaky_tests - - deterministic_tests - - mocked_dependencies - - binary_signals - - statistical_validation - - test_isolation - - predictable_inputs - - controlled_environment - nlp: "Deterministic validation framework requiring 100% pass rate in controlled environments, eliminating flaky tests, mocking dependencies for binary pass/fail signals" -evaluation: - success_signals: - - Test suite passes 10+ consecutive runs with identical results - - "No statistical assertions (no 95% success rate thresholds)" - - All external dependencies mocked with deterministic responses - - Fixed test data used (no Date.now, Math.random in tests) - - Binary pass/fail results (unambiguous for agent decision-making) - failure_signals: - - Test accepts statistical success rate (passes 19/20 times) - - Time-dependent test logic without mocking Date.now - - Tests interfere with each other (shared state not reset) - - Flaky tests tolerated (re-running CI until tests pass) - - Missing error path tests (only happy path covered) ---- - - -# Deterministic Validation Framework - -**Purpose**: Ensure all validation in agentic systems produces deterministic, repeatable results with 100% pass rate requirement in controlled environments. - -**Philosophy**: Agents require binary pass/fail signals, not probabilistic thresholds - statistical validation introduces unacceptable variance for automated decision-making. - ---- - -## When to Apply - -Use this framework when: - -- Writing tests for services (routing service, audit service, knowledge system) -- Designing CI/CD validation pipelines for automated deployments -- Creating validation scripts for agent-driven workflows -- Implementing quality gates in the trust-based execution model -- Evaluating whether existing tests meet agentic reliability standards - ---- - -## Quick Reference - -**Most Common Deterministic Test Patterns**: - -**1. Statistical → Deterministic Transformation**: -```typescript -// ❌ Statistical validation - introduces variance -describe('Routing Service', () => { - it('should have 95% success rate over 20 runs', async () => { - let successes = 0; - for (let i = 0; i < 20; i++) { - if (await routeRequest(testInput)) successes++; - } - expect(successes / 20).toBeGreaterThanOrEqual(0.95); // PROBABILISTIC - }); -}); - -// ✅ Deterministic validation - eliminates variance -describe('Routing Service', () => { - it('should route request correctly with known input', async () => { - const result = await routeRequest({ - context: 'task creation', - patterns: ['project_management'] - }); - expect(result.instructionFile).toBe('task_creation_workflow.instructions.md'); - expect(result.confidence).toBeGreaterThan(0.8); - }); -}); -``` - -**2. Fixed Test Data (No Randomness)**: -```typescript -// ❌ Non-deterministic - changes every test run -const testTimestamp = Date.now(); -const testId = Math.random().toString(); - -// ✅ Deterministic - same every test run -const testTimestamp = new Date('2025-10-27T12:00:00Z').getTime(); -const testId = 'test-routing-request-001'; -``` - -**3. Mock External Dependencies**: -```typescript -// ✅ Deterministic responses from mocked services -beforeEach(() => { - mockGitHubAPI({ - 'GET /repos/{owner}/{repo}/issues/42': { - status: 200, - body: { title: 'Task: Known Test Issue', state: 'open' } - } - }); -}); - -test('should fetch issue correctly', async () => { - const issue = await fetchIssue(42); - expect(issue.title).toBe('Task: Known Test Issue'); // Always this result -}); -``` - -**4. Isolated Database State**: -```typescript -// ✅ Each test gets fresh, isolated database state -beforeEach(async () => { - await resetTestDatabase(); - await seedTestData(FIXED_TEST_DATASET); -}); - -afterEach(async () => { - await cleanupTestDatabase(); -}); -``` - -**5. Flaky Test Detection**: -```bash -# Run test suite multiple times to detect flakiness -for i in {1..10}; do - npm test 2>&1 | tee "test-run-$i.log" -done - -# Analyze for inconsistent results -diff test-run-1.log test-run-10.log -``` - ---- - -## Core Principles - -- **100% Pass Rate Required**: No statistical variance acceptable in controlled environments - tests either pass or fail deterministically -- **Eliminate Flaky Tests**: Fix or remove tests with intermittent failures - no "usually works" tolerance -- **Predictable Inputs**: Use known test data with expected outcomes, never randomized or time-dependent values -- **Controlled Environment**: Isolate test conditions from external variables that introduce non-determinism -- **Clear Binary Signals**: Every validation produces unambiguous pass/fail result that agents can parse programmatically - -## Step-by-Step Guidance - -### Step 1: Replace Statistical Validation with Functional Validation - -Move from probability-based success rates to deterministic correctness testing. - -1. **Identify Statistical Tests**: - - Look for tests checking success rate thresholds (≥95%, ≥99%, etc.) - - Find tests with "acceptable failure" tolerances - - Locate tests using probabilistic assertions - - Expected outcome: List of tests requiring replacement - -2. **Design Functional Correctness Tests**: - ```typescript - // ❌ Statistical validation - introduces variance - describe('Routing Service', () => { - it('should have 95% success rate over 20 runs', async () => { - let successes = 0; - for (let i = 0; i < 20; i++) { - if (await routeRequest(testInput)) successes++; - } - expect(successes / 20).toBeGreaterThanOrEqual(0.95); // PROBABILISTIC - }); - }); - - // ✅ Deterministic validation - eliminates variance - describe('Routing Service', () => { - it('should route request correctly with known input', async () => { - const result = await routeRequest({ - context: 'task creation', - patterns: ['project_management', 'github_integration'] - }); - expect(result.instructionFile).toBe('task_creation_workflow.instructions.md'); - expect(result.confidence).toBeGreaterThan(0.8); - // Exact expected output every time - }); - }); - ``` - - Rationale: Deterministic tests reveal actual bugs, statistical tests mask intermittent failures - -3. **Implement 100% Pass Requirement**: - - Every test must pass every run in controlled environment - - No tolerance for flaky tests - - Success indicator: Test suite produces identical results across multiple runs - -### Step 2: Design Tests with Predictable Inputs - -Create test data that produces consistent, expected outcomes. - -1. **Use Fixed Test Data**: - ```typescript - // ❌ Non-deterministic - changes every test run - const testTimestamp = Date.now(); - const testId = Math.random().toString(); - - // ✅ Deterministic - same every test run - const testTimestamp = new Date('2025-10-27T12:00:00Z').getTime(); - const testId = 'test-routing-request-001'; - ``` - - Expected outcome: Test data identical across all runs - -2. **Mock External Dependencies**: - ```typescript - // ✅ Mock GitHub API for deterministic responses - beforeEach(() => { - mockGitHubAPI({ - 'GET /repos/{owner}/{repo}/issues/42': { - status: 200, - body: { title: 'Task: Known Test Issue', state: 'open' } - } - }); - }); - - test('should fetch issue correctly', async () => { - const issue = await fetchIssue(42); - expect(issue.title).toBe('Task: Known Test Issue'); // Always this result - }); - ``` - - Integration point: Isolates tests from external service variability - -3. **Avoid Time-Dependent Logic**: - - Mock `Date.now()`, `new Date()` in tests - - Use fixed timestamps for time-based validations - - Control async timing with deterministic delays - - Success indicator: Tests produce same results regardless of when executed - -### Step 3: Implement Comprehensive Error Handling Tests - -Validate that workflows handle expected error conditions gracefully. - -1. **Test Each Error Path**: - ```typescript - describe('Routing Service Error Handling', () => { - it('should handle missing instruction file gracefully', async () => { - const result = await routeRequest({ - context: 'nonexistent_domain' - }); - expect(result.error).toBe('NO_MATCHING_INSTRUCTION'); - expect(result.fallback).toBe('_template.instructions.md'); - expect(result.confidence).toBe(0); // Clear failure signal - }); - - it('should handle API timeout gracefully', async () => { - mockAPITimeout(); - const result = await routeRequest({ context: 'test' }); - expect(result.error).toBe('API_TIMEOUT'); - expect(result.retryable).toBe(true); - }); - }); - ``` - - Expected outcome: All error conditions tested and handled deterministically - -2. **Validate Graceful Degradation**: - - Test fallback behavior when primary path fails - - Verify system remains operational with reduced functionality - - Ensure error messages are actionable - - Rationale: Agents need predictable failure modes for decision-making - -### Step 4: Create Controlled Test Environments - -Isolate test execution from non-deterministic factors. - -1. **Database Isolation**: - ```typescript - // ✅ Each test gets fresh, isolated database state - beforeEach(async () => { - await resetTestDatabase(); - await seedTestData(FIXED_TEST_DATASET); - }); - - afterEach(async () => { - await cleanupTestDatabase(); - }); - ``` - - Expected outcome: No test pollution, each test starts with known state - -2. **Service Dependency Mocking**: - - Mock external services (GitHub API, MCP server, etc.) - - Use in-memory implementations for databases - - Control network conditions (no real HTTP calls in unit tests) - - Success indicator: Tests run offline without external dependencies - -3. **Resource Allocation Control**: - - Allocate sufficient resources for test execution - - Prevent resource contention between parallel tests - - Monitor for resource exhaustion during test runs - - Integration point: CI/CD pipeline provisions adequate resources - -### Step 5: Implement Operational Reliability Testing - -Test that services function correctly under expected operational conditions. - -1. **Dependency Availability Tests**: - ```typescript - describe('Service Dependencies', () => { - it('should verify routing service can access instruction files', async () => { - const instructionFile = await loadInstruction('task_creation_workflow'); - expect(instructionFile).toBeDefined(); - expect(instructionFile.frontmatter.title).toBeDefined(); - }); - - it('should verify audit service can write to event store', async () => { - const event = { type: 'ROUTING_DECISION', timestamp: FIXED_TIME }; - const result = await auditService.logEvent(event); - expect(result.success).toBe(true); - expect(result.eventId).toMatch(/^evt-/); - }); - }); - ``` - - Expected outcome: All required dependencies validated as operational - -2. **Permission Validation Tests**: - - Test that service accounts have required permissions - - Verify API tokens are valid and not expired - - Validate file system access permissions - - Success indicator: Permissions verified before deployment - -3. **Integration Point Tests**: - - Test cross-service communication (routing → audit logging) - - Validate message queue functionality - - Verify event emission and consumption - - Rationale: Prevents integration failures in production - -### Step 6: Fix or Remove Flaky Tests - -Systematically eliminate non-deterministic test behavior. - -1. **Identify Flaky Tests**: - ```bash - # Run test suite multiple times to detect flakiness - for i in {1..10}; do - npm test 2>&1 | tee "test-run-$i.log" - done - - # Analyze for inconsistent results - diff test-run-1.log test-run-10.log - ``` - - Expected outcome: List of tests with inconsistent results - -2. **Root Cause Analysis**: - - Race conditions in async code - - Uncontrolled timing dependencies - - External service dependencies - - Shared state between tests - - Common variation: Check for missing `await` keywords, improper mocking - -3. **Fix or Remove**: - - **Fix**: Address root cause (add proper mocking, fix race conditions, isolate state) - - **Remove**: Delete test if it cannot be made deterministic - - **Never Accept**: Tests with "acceptable" failure rates - - Success indicator: Test suite produces identical results on every run - -## Examples - -### Example 1: Routing Service Validation - -**Context**: Validating that the routing service correctly matches agent requests to instruction files - -**Scenario**: Agent needs to create a task, routing service must return task_creation_workflow.instructions.md - -```typescript -describe('Routing Service - Task Creation Context', () => { - const FIXED_REQUEST = { - context: 'task creation', - repoPath: '/path/to/project', - filePatterns: ['**'], - timestamp: new Date('2025-10-27T12:00:00Z').getTime() - }; - - beforeEach(() => { - // Mock file system for deterministic instruction file discovery - mockFileSystem({ - '/knowledge/instructions/project_management/task_creation_workflow.instructions.md': { - frontmatter: { - title: 'Task Creation Workflow', - applies_to: ['**'], - domains: ['project_management', 'agentic_workflows'], - priority: 'P0' - } - } - }); - }); - - it('should route to task creation workflow with high confidence', async () => { - const result = await routingService.matchInstructions(FIXED_REQUEST); - - // Deterministic assertions - expect(result.matches).toHaveLength(1); - expect(result.matches[0].file).toBe('task_creation_workflow.instructions.md'); - expect(result.matches[0].confidence).toBeGreaterThan(0.9); - expect(result.matches[0].reason).toContain('context match: "task creation"'); - }); - - it('should produce identical results on repeated calls', async () => { - const result1 = await routingService.matchInstructions(FIXED_REQUEST); - const result2 = await routingService.matchInstructions(FIXED_REQUEST); - const result3 = await routingService.matchInstructions(FIXED_REQUEST); - - // Results must be byte-for-byte identical - expect(result1).toEqual(result2); - expect(result2).toEqual(result3); - }); -}); -``` - -**Expected Result**: Tests pass 100% of the time with identical outputs, providing reliable signals for agent decision-making - -### Example 2: Audit Service Event Logging - -**Context**: Validating that audit events are captured correctly and consistently - -**Scenario**: Agent routing decisions must be logged for learning and compliance - -```typescript -describe('Audit Service - Event Capture', () => { - const FIXED_EVENT = { - type: 'ROUTING_DECISION', - timestamp: new Date('2025-10-27T12:00:00Z').getTime(), - agentId: 'test-agent-001', - decision: { - instruction: 'task_creation_workflow.instructions.md', - confidence: 0.95, - context: 'task creation' - } - }; - - beforeEach(async () => { - await resetTestDatabase(); - }); - - it('should log event with correct structure', async () => { - const result = await auditService.logEvent(FIXED_EVENT); - - expect(result.success).toBe(true); - expect(result.eventId).toMatch(/^evt-[a-z0-9]{8}$/); - - // Verify event stored correctly - const stored = await auditService.getEvent(result.eventId); - expect(stored.type).toBe('ROUTING_DECISION'); - expect(stored.agentId).toBe('test-agent-001'); - expect(stored.decision.confidence).toBe(0.95); - }); - - it('should handle concurrent event logging deterministically', async () => { - // All events should be captured, no race conditions - const events = Array(10).fill(null).map((_, i) => ({ - ...FIXED_EVENT, - agentId: `test-agent-${String(i).padStart(3, '0')}` - })); - - const results = await Promise.all( - events.map(e => auditService.logEvent(e)) - ); - - // All should succeed - expect(results.every(r => r.success)).toBe(true); - - // All should be retrievable - const stored = await Promise.all( - results.map(r => auditService.getEvent(r.eventId)) - ); - expect(stored).toHaveLength(10); - }); -}); -``` - -**Expected Result**: Event logging works deterministically even under concurrent load, providing reliable audit trail - -**Trade-offs**: More setup code for mocking, but eliminates flakiness that would undermine agent confidence - -### Example 3: Knowledge System Validation - -**Context**: Validating instruction file parsing and metadata extraction - -**Scenario**: System must parse instruction files consistently to enable routing - -```typescript -describe('Knowledge System - Instruction Parsing', () => { - const SAMPLE_INSTRUCTION = `--- -title: "Test Instruction" -description: "Sample instruction for testing" -applies_to: - - "**/*.ts" -domains: - - "validation" -priority: "P0" ---- - -# Test Instruction - -**Purpose**: Test purpose - -## Core Principles - -- Principle 1 -- Principle 2 -`; - - it('should parse instruction file frontmatter correctly', () => { - const parsed = parseInstructionFile(SAMPLE_INSTRUCTION); - - expect(parsed.frontmatter.title).toBe('Test Instruction'); - expect(parsed.frontmatter.applies_to).toEqual(['**/*.ts']); - expect(parsed.frontmatter.domains).toContain('validation'); - expect(parsed.frontmatter.priority).toBe('P0'); - }); - - it('should extract sections with correct structure', () => { - const parsed = parseInstructionFile(SAMPLE_INSTRUCTION); - - expect(parsed.sections).toHaveProperty('purpose'); - expect(parsed.sections).toHaveProperty('core_principles'); - expect(parsed.sections.core_principles).toHaveLength(2); - }); - - it('should produce identical parse results every time', () => { - const parsed1 = parseInstructionFile(SAMPLE_INSTRUCTION); - const parsed2 = parseInstructionFile(SAMPLE_INSTRUCTION); - const parsed3 = parseInstructionFile(SAMPLE_INSTRUCTION); - - expect(parsed1).toEqual(parsed2); - expect(parsed2).toEqual(parsed3); - }); -}); -``` - -**Expected Result**: Parsing is completely deterministic, enabling reliable instruction routing - -## Validation Checklist - -Complete before marking validation implementation as done: - -### Test Design Quality -- [ ] All tests use fixed, predictable inputs (no randomness, no Date.now()) -- [ ] External dependencies mocked with deterministic responses -- [ ] Each test isolates its state (database reset, no shared state) -- [ ] Error paths tested with specific expected outcomes -- [ ] Tests produce binary pass/fail (no probabilistic assertions) - -### Determinism Verification -- [ ] Test suite runs successfully 10+ times consecutively with identical results -- [ ] No flaky tests identified (all pass consistently) -- [ ] Tests run offline without external service dependencies -- [ ] Parallel test execution produces same results as serial -- [ ] CI/CD pipeline shows 100% pass rate over multiple commits - -### Coverage Requirements -- [ ] All critical paths tested (routing, audit logging, knowledge parsing) -- [ ] All error conditions tested with expected graceful handling -- [ ] Integration points between services tested -- [ ] Resource constraints tested (permissions, dependencies) -- [ ] Operational readiness validated (services can start, connect, operate) - -## Common Pitfalls - -### Pitfall 1: Accepting Statistical Success Rates - -- ❌ **Problem**: Using 95% success threshold instead of 100% pass requirement -- **Why it happens**: Porting tests from human-driven development where occasional failures are tolerated -- ✅ **Solution**: Replace statistical assertions with deterministic functional correctness tests -- **Example**: Instead of "passes 19/20 times", fix the root cause so it passes 20/20 times - -### Pitfall 2: Time-Dependent Test Logic - -- ❌ **Problem**: Tests use `Date.now()`, `setTimeout` without mocking, causing non-deterministic behavior -- **Why it happens**: Didn't recognize time as external dependency requiring control -- ✅ **Solution**: Mock all time-related functions, use fixed timestamps in test data -- **Example**: Mock `Date.now()` to return fixed timestamp, use deterministic delays - -### Pitfall 3: Shared State Between Tests - -- ❌ **Problem**: Tests pollute shared resources (database, files, globals), causing failures when run in different orders -- **Why it happens**: Insufficient isolation in test setup/teardown -- ✅ **Solution**: Reset all state before each test, use isolated test databases -- **Example**: Each test gets fresh database seeded with known test data - -### Pitfall 4: Ignoring Flaky Tests - -- ❌ **Problem**: Accepting tests that "usually pass" or re-running CI until tests pass -- **Why it happens**: Treating symptoms instead of addressing root cause -- ✅ **Solution**: Fix flaky tests immediately or remove them - no tolerance for non-determinism -- **Example**: Test fails intermittently due to race condition - add proper synchronization or remove test - -### Pitfall 5: Insufficient Error Path Testing - -- ❌ **Problem**: Only testing happy path, missing error conditions that agents will encounter -- **Why it happens**: Focusing on functionality over reliability -- ✅ **Solution**: Test every error path with expected graceful handling -- **Example**: Test API timeout, missing file, invalid input, permission denied - all with deterministic outcomes - -## Edge Cases - -### Edge Case 1: Non-Deterministic External Services - -**When**: Tests require external service (GitHub API, MCP server) that cannot be made deterministic - -**Approach**: -- Separate unit tests (mocked, deterministic) from integration tests (real services) -- Mark integration tests clearly, run separately from core test suite -- Provide mock implementations that match real service behavior exactly -- Consider contract testing to validate mocks match real APIs - -**Example**: Routing service unit tests use mocked instruction file system (deterministic), integration tests use real file system (run separately) - -### Edge Case 2: Probabilistic Algorithms Requiring Validation - -**When**: Service uses ML model or heuristic with inherent probability (e.g., confidence scores) - -**Approach**: -- Test with fixed inputs that produce known confidence scores -- Validate confidence calculation logic, not the score itself -- Use threshold tests with deterministic boundaries -- Document expected score ranges for known inputs - -**Example**: Routing confidence score test uses fixed context that consistently produces 0.85-0.95 confidence, validates score is in range - -### Edge Case 3: Race Conditions in Concurrent Operations - -**When**: Service handles concurrent requests and tests need to validate thread safety - -**Approach**: -- Use deterministic concurrency testing frameworks -- Control execution order with synchronization primitives -- Test with fixed concurrency levels (not random) -- Validate all concurrent operations complete successfully - -**Example**: Audit service handles 10 concurrent events, test validates all 10 are captured without data loss - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| Test passes locally but fails in CI | Environment differences (time zone, locale, resources) | Mock environment variables, use Docker for consistent environment | -| Test results vary between runs | Non-deterministic inputs (Date.now(), Math.random()) | Replace with fixed test data, mock time-related functions | -| Tests interfere with each other | Shared state not reset between tests | Add proper beforeEach/afterEach hooks to isolate state | -| Tests timeout intermittently | External service delays or resource contention | Mock external services, increase resource allocation, add timeout controls | -| Flaky test cannot be fixed | Fundamental non-determinism in code under test | Remove test and fix underlying code, or mark as integration test | -| 100% pass rate in controlled env, failures in production | Test environment doesn't match production | Enhance integration tests, add production monitoring, validate assumptions | - -## Related Instructions - -- **See also**: [trust_based_task_execution.instructions.md](../trust_execution/trust_based_task_execution.instructions.md) - P##.CV## (Completion Validation) requires deterministic validation -- **Prerequisites**: [feature_development.instructions.md](../trust_execution/feature_development.instructions.md) - Quality gates depend on deterministic validation -- **Next steps**: [agentic_decision_making.instructions.md](../agentic_workflows/agentic_decision_making.instructions.md) - Agents use validation results for decision-making - ---- - -**Success Criteria**: All validation produces deterministic, repeatable results with 100% pass rate in controlled environments, providing reliable binary signals for agent decision-making. - -**Confidence Check**: Can the test suite run 10 times consecutively with identical results? Are there any probabilistic assertions or acceptable failure rates? Do tests isolate their state completely? diff --git a/.pongogo/instructions/validation/validation_essentials.instructions.md b/.pongogo/instructions/validation/validation_essentials.instructions.md deleted file mode 100644 index 1aea5ce8..00000000 --- a/.pongogo/instructions/validation/validation_essentials.instructions.md +++ /dev/null @@ -1,389 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Validation Essentials" -description: "Essential validation patterns, requirements, and quality gates." -applies_to: - - "**/*" -domains: - - "validation" -priority: "P1" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 1 - triggers: - keywords: - - validation_essentials - - quality_gates - - 100%_pass_rate - - deterministic_validation - - production_success - - completion_criteria - - verification_efficiency - - flaky_tests - - epic_validation - - operational_validation - nlp: "Essential validation standards with quality gates, 100% pass rate in controlled environments, 95% production success, verification efficiency, deterministic testing" -evaluation: - success_signals: - - "Controlled environment tests achieve 100% pass rate" - - "Production workflows maintain 95%+ success rate" - - Verification efficiency protocol followed (max 2-3 checks) - - Quality gates enforced before completion - failure_signals: - - "Tests pass at less than 100% in controlled environment" - - Flaky tests accepted instead of fixed - - Endless re-verification exceeding budget - - Friction signals ignored during execution ---- - - -# Validation Essentials - -**Purpose**: Establish essential validation standards ensuring quality gates, testing protocols, and completion criteria maintain the integrity of agent-first architecture. - -**Philosophy**: Deterministic validation with 100% pass rates in controlled environments is non-negotiable for agentic systems where agents must make reliable, repeatable decisions. - ---- - -## When to Apply - -This instruction applies when: - -- **Scenario 1**: Implementing quality gates for any service (API, CLI, MCP server) -- **Scenario 2**: Designing test suites for microservices or integration workflows -- **Scenario 3**: Validating completion of Epics, Tasks, or deployment phases -- **Scenario 4**: Creating CI/CD pipelines with automated validation steps -- **Scenario 5**: Defining acceptance criteria for feature development - ---- - -## Quick Reference - -**Key Validation Standards**: - -**1. Pass Rate Thresholds** (Critical Distinction): -- **Controlled Test Environment**: 100% pass rate required (zero tolerance for flaky tests) -- **Production Workflows**: 95% minimum success rate under normal conditions -- **Critical Services**: May require 99%+ success rate for high-impact paths - -**2. Deterministic Test Checklist**: -- [ ] Uses fixed, predictable inputs (no `Date.now()`, `Math.random()`) -- [ ] External dependencies mocked with deterministic responses -- [ ] Each test isolates its state (database reset, no shared globals) -- [ ] Same test run multiple times produces identical results -- [ ] Tests run offline without external service dependencies - -**3. Verification Efficiency Protocol**: -- **First verification**: Perform full validation and document result -- **Second verification**: Confirm previous result if state may have changed -- **Third verification**: Final check before critical operation -- **After 3rd verification**: Trust documented verification, do not re-check -- **Rationale**: Scales linearly O(N), not quadratically O(N²) - -**4. Quality Gate Decision Points**: -``` -Can Epic/Task be marked complete? -├─ Operational validation 100% pass? NO → FIX tests, BLOCK completion -├─ Operational validation 100% pass? YES - ├─ Production success ≥ 95%? NO → Investigate, BLOCK completion - ├─ Production success ≥ 95%? YES - ├─ Dependencies verified ≥ 95%? NO → Verify dependencies - ├─ Dependencies verified ≥ 95%? YES - ├─ Integration tests 100% pass? NO → Fix integration tests - └─ Integration tests 100% pass? YES → ✅ READY for completion -``` - -**5. Completion Validation Requirements** (All must pass): -- **Operational Validation**: 100% pass rate on all operational tests -- **Dependency Verification**: All dependencies confirmed operational (95%+ success) -- **Integration Testing**: All agentic integration points validated (100% pass) -- **Systematic Prevention**: All identified failure modes addressed - -**6. When to Block Deployment** (Non-negotiable): -- Controlled test environment shows < 100% pass rate -- Production success rate < 95% over observation period -- Flaky tests detected (intermittent failures) -- Dependencies not verified operational -- Rollback procedure not tested - -**7. User Expectation Validation** (NEW - Routing IMP-018): - -Friction signals often indicate validation gaps where implementation diverged from user expectations: - -**Friction Signals → Validation Gaps**: -| Friction Signal | What It Reveals | Validation Action | -|-----------------|-----------------|-------------------| -| "that's not what I expected" | Output validation missing | Add expected output check | -| "you skipped the tests" | Sequence validation missing | Add prerequisite gate | -| "wait, I wanted to review first" | Approval gate missing | Add user confirmation step | -| "we already discussed this" | Context validation missing | Verify understanding before proceeding | - -**Expectation Validation Protocol**: -1. **Before execution**: Confirm understanding of expected outcome -2. **During execution**: Check for friction signals (pause if detected) -3. **After completion**: Verify output matches expectation (not just "works") - -**Why This Matters**: -- Technical validation (code works) ≠ Expectation validation (output matches intent) -- Friction signals are real-time feedback that expectation validation failed -- Capturing friction patterns improves future validation criteria - ---- - -## Core Principles - -- **100% Pass Rate Standard**: All validation tests must achieve 100% pass rates in controlled test environments - no exceptions for core operational validation -- **Deterministic Validation Required**: Validation must be deterministic and repeatable; same inputs always produce same outputs in controlled environments -- **Verification Efficiency**: Maximum 2-3 verifications of the same information per task; after limit reached, trust previous verification -- **Production Success Threshold**: Minimum 95% success rate for production workflows under normal conditions -- **Binary Outcomes Only**: Clear pass/fail criteria with no statistical ambiguity or probabilistic signals - -## Step-by-Step Guidance - -1. **Define Validation Scope** - - Identify what needs validation (service endpoint, integration workflow, feature completion) - - Determine test environment requirements (isolated, controlled, production-like) - - Expected outcome: Clear validation boundaries with explicit test conditions - -2. **Design Deterministic Tests** - - Create predictable inputs with known expected outputs - - Ensure repeatable results independent of external factors - - Rationale: Agents require reliable, binary pass/fail signals for decision-making - - Success indicator: Same test run multiple times produces identical results - -3. **Implement Quality Gates** - - Establish 100% pass rate requirement for controlled environments - - Set 95% minimum success threshold for production workflows - - Common variation: Service-specific thresholds may be higher (99%+) for critical paths - - Integration point: CI/CD pipeline enforces quality gates before deployment - -4. **Apply Verification Efficiency** - - Limit re-verification to 2-3 checks per task or validation point - - Document verification status in summaries or handoff notes - - Success indicator: Validation time scales linearly (O(N)), not quadratically (O(N²)) - -5. **Validate Completion Criteria** - - Operational validation: 100% pass rate on all operational tests - - Dependency verification: All workflow dependencies confirmed operational (95%+ success) - - Integration testing: All agentic integration points validated (100% pass) - - Systematic prevention: All identified failure modes addressed - -## Examples - -### Example 1: MCP Server Endpoint Validation - -```bash -# Deterministic test for MCP server health endpoint -# Expected: 200 OK with valid JSON response containing status field - -# Test script: tests/mcp_server/health_check.test.ts -describe('MCP Server Health Endpoint', () => { - test('returns 200 OK with valid status JSON', async () => { - const response = await fetch('http://localhost:3000/health'); - expect(response.status).toBe(200); - - const data = await response.json(); - expect(data).toHaveProperty('status'); - expect(['healthy', 'degraded']).toContain(data.status); - }); -}); - -# CI/CD validation gate -# Must pass 100% in test environment before deployment -npm test -- tests/mcp_server/health_check.test.ts -``` - -**Context**: MCP server health checks enable agents to verify service availability before routing decisions. Deterministic validation ensures agents receive reliable signals. - -**Expected Result**: Test passes 100% of the time in controlled environment; any failure indicates service configuration issue requiring immediate investigation. - -### Example 2: Agent Routing Service Integration Test - -```typescript -// tests/integration/agent_routing.test.ts -// Validates agent instruction routing based on file patterns - -import { RoutingService } from '{package}/routing'; -import { InstructionRegistry } from '{package}/knowledge'; - -describe('Agent Routing Service Integration', () => { - let routingService: RoutingService; - let registry: InstructionRegistry; - - beforeEach(() => { - // Controlled test environment with fixed instruction set - registry = new InstructionRegistry('./fixtures/instructions'); - routingService = new RoutingService(registry); - }); - - test('routes GitHub workflow files to github_integration instructions', async () => { - const filePath = '.github/workflows/ci.yml'; - const instructions = await routingService.getInstructionsFor(filePath); - - // Deterministic expectation: GitHub files always match github_integration domain - expect(instructions).toContainEqual( - expect.objectContaining({ domain: 'github_integration' }) - ); - }); - - test('routes validation scripts to validation domain instructions', async () => { - const filePath = 'scripts/validate-deployment.sh'; - const instructions = await routingService.getInstructionsFor(filePath); - - expect(instructions).toContainEqual( - expect.objectContaining({ domain: 'validation' }) - ); - }); -}); -``` - -**Context**: Routing service is critical infrastructure enabling agent-first architecture. 100% pass rate ensures agents always receive correct contextual guidance. - -**Trade-offs**: Deterministic tests require fixture data, which must be maintained. Trade-off accepted because routing reliability is foundational. - -### Example 3: Epic Completion Validation Checklist - -```markdown -## Epic Validation Checklist - [Epic]-api_gateway - -**Quality Gates - ALL must pass before Epic completion:** - -- [x] **Operational Validation**: 100% pass rate on all operational tests (12/12 tests passing) - - Gateway health check: PASS - - Authentication middleware: PASS - - Rate limiting: PASS - - Request routing: PASS - - Error handling: PASS - - Logging integration: PASS - - (6 additional tests: all PASS) - -- [x] **Dependency Verification**: All workflow dependencies operational (98.3% success over 7 days) - - Auth service availability: 99.1% - - Database connection pool: 99.8% - - Redis cache: 97.2% - - (Minimum 95% threshold: MET) - -- [x] **Integration Testing**: All agentic integration points validated (100% pass) - - MCP server discovery: PASS - - CLI command integration: PASS - - Agent request routing: PASS - -- [x] **Systematic Prevention**: All identified failure modes addressed - - Circuit breaker for downstream failures: IMPLEMENTED - - Graceful degradation for cache outages: IMPLEMENTED - - Rollback procedure verified: TESTED - -**Epic Status**: ✅ READY FOR COMPLETION -``` - -**Context**: Epic validation ensures work is not just deployed but operational and effective. Checklist provides clear binary gates for agents and humans. - -**Expected Result**: Epic closure only occurs when all checkboxes pass; any failure blocks completion and triggers remediation workflow. - -## Validation Checklist - -- [ ] All validation tests designed with deterministic, predictable inputs and expected outputs -- [ ] Controlled test environment achieves 100% pass rate (zero tolerance for flaky tests) -- [ ] Production workflows monitored for 95%+ success rate under normal conditions -- [ ] Verification efficiency maintained (max 2-3 checks per validation point) -- [ ] Quality gates enforced in CI/CD pipeline before deployment -- [ ] Completion criteria includes operational validation, dependency verification, and integration testing -- [ ] All test failures trigger root cause analysis and systematic prevention implementation -- [ ] Rollback procedures verified operational before Epic/Task completion - -## Common Pitfalls - -### Pitfall 1: Statistical Validation in Controlled Environments - -- ❌ **Problem**: Using "95% success over 20 runs" as acceptance criteria introduces statistical variance making it unreliable for agent decision-making -- **Why it happens**: Developers confuse production success rate monitoring (95%+ acceptable) with controlled test validation (100% required) -- ✅ **Solution**: Use deterministic functional correctness validation in controlled environments; reserve statistical monitoring for production observability -- **Example**: Test "authentication endpoint returns 200 OK for valid credentials" should pass 100% in controlled environment, not 95% - -### Pitfall 2: Endless Re-Verification - -- ❌ **Problem**: Reading the same configuration file 5+ times, checking the same prerequisite repeatedly, re-validating already confirmed states -- **Why it happens**: Lack of trust in previous verification results or unclear verification status tracking -- ✅ **Solution**: Document verification status explicitly; trust documented verification after 2-3 checks; implement verification efficiency protocol -- **Example**: After confirming Docker service is running 2 times, trust that status and proceed; don't check again unless there's evidence of state change - -### Pitfall 3: Incomplete Completion Criteria - -- ❌ **Problem**: Declaring work "done" without running validation test suite or verifying quality gates pass -- **Why it happens**: Pressure to complete tasks quickly or misunderstanding of "done" definition -- ✅ **Solution**: All quality gates must pass before completion; use Epic Validation Standards checklist as mandatory gate -- **Example**: Feature implementation complete but not validated is NOT done; validation must show 100% pass in controlled environment - -### Pitfall 4: Ignoring Friction Signals (Routing IMP-018) - -- ❌ **Problem**: Continuing execution when user expresses "wait", "that's not what I", "you're skipping" signals -- **Why it happens**: Focus on technical validation while missing expectation validation -- ✅ **Solution**: Treat friction signals as real-time validation failures; PAUSE immediately, clarify, resume correctly -- **Example**: User says "wait, I wanted to review first" → STOP → This signals missing approval gate → Add confirmation step - -## Edge Cases - -### Edge Case 1: Service Degradation in Production - -**When**: Production success rate drops below 95% threshold but controlled environment tests still pass at 100% - -**Approach**: -1. Confirm controlled tests still pass (validates core logic is sound) -2. Investigate production-specific factors (load, dependencies, network) -3. Implement production-specific fixes (caching, circuit breakers, rate limiting) -4. Monitor recovery to 95%+ threshold before resuming feature work - -**Example**: API gateway shows 89% production success but all unit tests pass. Investigation reveals downstream service timeout under load. Solution: Add circuit breaker and increase timeout for that dependency. - -### Edge Case 2: Flaky Tests in CI/CD - -**When**: Tests pass locally at 100% but fail intermittently (< 100%) in CI/CD pipeline - -**Approach**: -1. DO NOT lower pass rate threshold or ignore flaky tests -2. Investigate root cause: timing issues, environmental differences, resource constraints -3. Fix test or environment to achieve 100% pass rate -4. If test design is flawed, redesign test to be deterministic - -**Example**: Integration test fails 10% of the time in CI due to race condition. Solution: Add proper wait conditions or synchronization, not "rerun until it passes." - -### Edge Case 3: Third-Party Dependency Failures - -**When**: Validation depends on external service (GitHub API, cloud provider) outside direct control - -**Approach**: -1. Separate internal validation (100% pass required) from external dependency checks -2. Use mocking/stubbing for external dependencies in controlled tests -3. Monitor external dependency success rates separately (95%+ acceptable) -4. Implement graceful degradation for external failures - -**Example**: GitHub API rate limiting affects validation. Solution: Mock GitHub API for controlled tests (100% pass), monitor real API separately (95%+ acceptable). - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| Tests pass locally but fail in CI | Environmental differences (timing, resources, configuration) | Investigate CI environment; fix test to be environment-independent or normalize CI setup | -| Validation takes too long (> 10 minutes) | Excessive re-verification or redundant checks | Apply verification efficiency protocol; document verification status; trust previous checks | -| Production success rate < 95% but tests pass | Production-specific load, dependencies, or environmental factors | Investigate production conditions; implement production-specific mitigations (caching, circuit breakers) | -| Flaky tests (< 100% pass rate) | Non-deterministic test design (race conditions, timing dependencies) | Redesign test for determinism; add proper synchronization; fix test environment | -| Quality gates ignored/bypassed | Unclear enforcement or missing CI/CD integration | Integrate quality gates into CI/CD pipeline as mandatory checks; block deployment on failure | -| Agents make incorrect routing decisions | Validation passed but doesn't cover agent decision logic | Add integration tests validating agent-facing APIs; ensure agent decision paths are tested | - -## Related Instructions - -- **See also**: [Deterministic Validation Framework](./deterministic_validation_framework.instructions.md) - Comprehensive framework for designing deterministic validation systems -- **See also**: [Verification Efficiency](./verification_efficiency.instructions.md) - Detailed protocol for avoiding endless re-verification -- **See also**: [Epic Validation Standards](./epic_validation_standards.instructions.md) - Complete Epic completion criteria and quality gates -- **See also**: [Project Glossary](../../wiki/Project-Glossary.md) - Authoritative source for PM terminology (Epic, Task, Sub-Task, Sub-Issue) -- **See also**: [Glossary Maintenance](../project_management/glossary_maintenance.instructions.md) - Keeping glossary current and complete -- **Prerequisites**: [Development Workflow Essentials](../trust_execution/development_workflow_essentials.instructions.md) - Understanding of Epic/Task structure before applying validation -- **Next steps**: [Quality Gate Compliance](./quality_gate_compliance.instructions.md) - Advanced quality gate implementation patterns - ---- - -**Success Criteria**: Validation tests achieve 100% pass rate in controlled environments, production workflows maintain 95%+ success rate, quality gates enforced in CI/CD, and Epic/Task completion requires passing all validation criteria. - -**Confidence Check**: Can you articulate the difference between 100% pass rate in controlled environments vs. 95% success rate in production? Do your validation tests produce deterministic, repeatable results? diff --git a/.pongogo/instructions/validation/verification_efficiency.instructions.md b/.pongogo/instructions/validation/verification_efficiency.instructions.md deleted file mode 100644 index 8b0ddef8..00000000 --- a/.pongogo/instructions/validation/verification_efficiency.instructions.md +++ /dev/null @@ -1,400 +0,0 @@ ---- -pongogo_instruction_spec: "0.0.2" -title: "Verification Efficiency" -description: "Efficient verification strategies to minimize redundant checks and optimize workflows." -applies_to: - - "**/*" -domains: - - "validation" -priority: "P1" -pongogo_version: "2026-02-12" -source: "Original" - -routing: - priority: 0 - triggers: - keywords: - - verification_efficiency - - diminishing_returns - - verification_budget - - cross-session_trust - - O(N)_complexity - - re-verification - - trust_protocol - - session_summary - - state_change - - verification_count - nlp: "Verification efficiency with diminishing returns, verification budgets, cross-session trust protocols preventing O(N²) waste through trust directives" -evaluation: - success_signals: - - Verification budget checked before any file read (max 3x same file) - - Cross-session trust applied (documented verifications not repeated) - - Summary includes explicit DO NOT verify directives with counts - - O(N) time complexity maintained (not O(N²) from re-verification) - - Trust decisions documented with rationale - failure_signals: - - Same file read 5+ times in one task (budget exceeded) - - New session triggers re-verification of everything - - Ambiguous summary statements without explicit directives - - State change paranoia (assuming files changed without evidence) - - Verification count not documented in session summaries ---- - - -# Verification Efficiency Framework - -**Purpose**: Eliminate redundant verification operations across sessions through verification budgets and trust protocols preventing O(N²) time waste. - -**Philosophy**: After 2-3 verifications, additional checks add near-zero value while consuming resources—trust previous verification and proceed to implementation. - ---- - -## When to Apply - -Use verification efficiency protocols when: - -- Working on multi-session tasks spanning days or multiple conversations -- Files have been read multiple times in current or previous sessions -- Previous session summaries document verification counts -- About to re-read files already verified and unchanged -- Implementing features requiring cross-session coordination - ---- - -## Quick Reference - -**Key Verification Efficiency Criteria**: - -**1. Verification Budget Limits** (Hard Stops): -- **Same file read**: Maximum 3x per task -- **Same prerequisite check**: Maximum 2x per session -- **Same validation**: Maximum 2x across all sessions -- **Rule**: If limit reached → TRUST previous verification, do NOT re-verify - -**2. Trust Decision Tree**: -``` -About to verify something? -├─ Was it verified in current session? YES → TRUST, don't re-verify -├─ Was it verified in previous session (documented)? YES → TRUST, don't re-verify -├─ Has file changed since last verification? NO → TRUST, don't re-verify -├─ Verification count at budget limit (2-3x)? YES → TRUST, don't re-verify -└─ First or second verification? → Proceed with verification -``` - -**3. Cross-Session Trust Protocol**: -- ✅ **DO**: Read session summary, note verification counts, trust documented results -- ✅ **DO**: State "Implementation verified in session 2025-01-26" and proceed to next segment -- ❌ **DON'T**: Re-read files to "confirm" they're still valid -- ❌ **DON'T**: Re-run validations already documented as passing - -**4. Summary Documentation Requirements**: -```markdown -## Session Summary - -**Verifications Performed**: -- `file.ts`: Read 2x (initial + validation check) -- `config.yml`: Read 1x (sufficient for implementation) -- **Verification Count**: 3 total file reads this session - -**Action Directive for Next Session**: -- DO NOT re-verify file.ts (already validated 2x) -- DO NOT re-read config.yml (unchanged, trusted) -- Proceed directly to validation segment implementation -``` - -**5. O(N) vs O(N²) Time Complexity**: -- **O(N²) Anti-Pattern**: N tasks each re-verifying all N prerequisites = N² operations -- **O(N) Correct**: N tasks each trust prior verifications = N operations -- **Example**: 10 tasks with O(N²) = 100 verification operations vs O(N) = 10 operations - -**6. Diminishing Returns Formula**: -``` -Verification Value: -- 1st verification: 95% confidence → High value -- 2nd verification: 95% → 99% confidence → Moderate value -- 3rd verification: 99% → 99.5% confidence → Low value -- 4th+ verification: <0.5% additional confidence → Waste - -After K=2-3 verifications: STOP, trust result, proceed -``` - ---- - -## Core Principles - -- **Law of Diminishing Returns**: After K=2-3 verifications, additional checks waste resources without improving confidence -- **Verification Budget Limits**: Maximum 3x same file, 2x same prerequisite across all sessions -- **Cross-Session Trust**: Trust documented verification from previous sessions without re-reading -- **Explicit Action Directives**: Summaries must state "DO NOT verify" to prevent next-session loops -- **O(N) Not O(N²)**: Linear time complexity for N tasks, not quadratic from repeated verification - -## Step-by-Step Guidance - -### 1. **Check Verification History Before Reading** - - Review current context: Has this file been read in current session? - - Check session summary: Does summary document prior verification count? - - Count total verifications: How many times has this information been verified? - - Expected outcome: Clear understanding of verification history before acting - -### 2. **Apply Verification Budget Rules** - - Same file read: Maximum 3 times per task - - Same prerequisite check: Maximum 2 times per session - - Same validation: Maximum 2 times across all sessions - - If limit reached: TRUST previous verification, do NOT re-verify - - Expected outcome: Verification budget preserved, redundant operations prevented - -### 3. **Make Trust Decision** - - If verification count ≥ 2 AND no state change: TRUST existing information - - If verification count < 2: Proceed with verification, document count - - If state changed (git commits): Reset count, justify re-verification - - Document decision: "Trusting because..." or "Verifying because..." - - Expected outcome: Conscious decision with documented rationale - -### 4. **Document Verification Status in Summaries** - - Include verification status section: List files read and counts - - State verification budget: "3/9 used (OK)" or "APPROACHING LIMIT" - - Add explicit directives: "DO NOT read X.md (verified 3x already)" - - Add trust directives: "TRUST X.md line 47 content (verified 3x)" - - Expected outcome: Next session has clear verification history and directives - -### 5. **Apply Cross-Session Trust Protocol** - - When receiving "DO NOT verify" directive: Skip verification, proceed directly - - When receiving "TRUST verified info" directive: Use information without re-reading - - When summary documents K≥2 verifications: Trust unless state changed - - Expected outcome: Cross-session trust prevents verification loops - -## Examples - -### Example 1: Routing Service Development (Multi-Session) - -Context: Implementing routing service over 3 days, architecture document read multiple times - -```markdown -## Session 1: Initial Analysis (Day 1) -- Read architecture.md (verification count: 1) -- Document: "Architecture: microservices with routing service + API gateway" -- Summary verification status: - - architecture.md: Read 1x - - Budget: 1/3 used (OK) - -## Session 2: Service Implementation (Day 2) -Summary from Day 1: "architecture.md verified 1x - microservices + gateway" - -❌ WRONG: Re-Analysis Loop -"Let me re-read architecture.md to refresh my memory..." -- Wastes verification budget (2/3 used) -- Adds no new information -- Delays implementation - -✅ CORRECT: Trust Protocol -Decision: TRUST Day 1 verification, DO NOT re-read -Rationale: No architecture changes, budget preserved, proceed with implementation -Action: Implement routing service following documented microservices pattern - -## Session 3: Integration Testing (Day 3) -Summary from Day 2: "architecture.md verified 1x (Day 1) - DO NOT re-verify" - -✅ CORRECT: Trust Directive Applied -Decision: TRUST directive, skip architecture re-verification -Rationale: Verification efficiency protocol, cross-session trust -Action: Write integration tests using microservices assumptions from Day 1 - -Result: -- Verification budget: 1x instead of 3x (67% reduction) -- O(N) time complexity maintained (not O(N²)) -- Faster execution: Implementation starts Day 2, not Day 4 -``` - -**Context**: Multi-day routing service implementation -**Expected Result**: Linear time complexity, efficient cross-session trust, rapid implementation - -### Example 2: Microservices Context Verification - -Context: Validating microservices architecture for multiple services in single session - -```markdown -## Verification Budget Tracking - -### First Service: Authentication -- Read docker-compose.yml (count: 1) - microservices confirmed -- Read architecture.md (count: 1) - service patterns documented -- Document: "Docker Compose uses microservices architecture" - -### Second Service: Routing -Summary states: "docker-compose.yml verified 1x, architecture.md verified 1x" - -❌ WRONG: Redundant Re-Verification -"Let me re-read docker-compose.yml to see the architecture..." -- Verification count: 2/3 (approaching limit) -- No new information gained -- Wastes cognitive resources - -✅ CORRECT: Trust Within Session -Decision: TRUST session verification, DO NOT re-read -Rationale: Same session, no docker-compose changes, trust verified architecture -Action: Implement routing service using verified microservices patterns - -### Third Service: API Gateway -Summary states: "docker-compose.yml verified 1x - DO NOT re-read" - -✅ CORRECT: Trust Directive -Decision: TRUST directive, implement directly -Rationale: Budget preserved, architecture unchanged, verified patterns apply -Action: Create API gateway service following verified patterns - -Result: -- Verification budget: 1x for all 3 services (not 3x) -- Consistent architecture understanding across services -- Cognitive efficiency: No re-processing of same information -``` - -**Context**: Within-session trust for multiple microservices -**Expected Result**: Single verification supports multiple implementations efficiently - -### Example 3: Emergency Override with State Change - -Context: Architecture document modified mid-session requiring re-verification - -```markdown -## Session Flow with State Change Detection - -### Initial State -- Read architecture.md (count: 1) -- Document: "Event-driven messaging with RabbitMQ" - -### Implementation Phase -Decision: TRUST verification, implement messaging service -Action: Create RabbitMQ consumers and producers - -### State Change Detected -Git commit detected: "Update architecture.md - Switch to Kafka for messaging" - -### Re-Verification Decision -Question: Verification budget suggests trusting, but state changed? - -✅ CORRECT: Override for State Change -Decision: Re-verify architecture.md despite budget (count: 2) -Rationale: Git commit shows file changed, state verification required -Documentation: "Re-verifying architecture.md because git commit SHA -showed state change from RabbitMQ to Kafka - safety overrides efficiency" -Action: Read updated architecture, refactor from RabbitMQ to Kafka - -Result: -- State change detected and handled correctly -- Override documented with evidence (commit SHA) -- Safety preserved while respecting efficiency protocols -``` - -**Context**: State change detection in architecture documentation -**Expected Result**: Safety overrides efficiency when state changes, with documented justification - -## Validation Checklist - -Before ANY file read operation: - -- [ ] Check if information already in current context -- [ ] Review summary for prior verification count -- [ ] Verify verification count < budget limit (3x file, 2x prerequisite) -- [ ] Check for state changes (git commits, timestamps) -- [ ] Document decision rationale ("Trusting because..." or "Verifying because...") -- [ ] If re-verifying, document justification for override - -After creating session summary: - -- [ ] Verification status section included with counts -- [ ] Verification budget status documented (OK/APPROACHING/EXHAUSTED) -- [ ] Explicit "DO NOT verify" directives for exhausted budget -- [ ] Explicit "TRUST" directives for verified information -- [ ] Next actions specified without ambiguity - -## Common Pitfalls - -### Pitfall 1: "Verify Before Acting" Loop - -- ❌ **Problem**: Reading same files every session before implementing -- **Why it happens**: Not applying cross-session trust protocols -- ✅ **Solution**: Check verification history, trust if count ≥ 2 and state unchanged -- **Example**: Reading work log 5 times across 3 sessions → Trust after 2nd verification, proceed directly - -### Pitfall 2: "Just To Be Safe" Re-Verification - -- ❌ **Problem**: Re-verifying despite documented validation with no state change -- **Why it happens**: Distrust of previous verification without evidence -- ✅ **Solution**: Trust documented verification unless git/timestamp indicates change -- **Example**: "Let me double-check the architecture..." → Trust verified architecture, implement directly - -### Pitfall 3: Ambiguous Summary Statements - -- ❌ **Problem**: Summary says "ready to proceed" without explicit directives -- **Why it happens**: Vague language doesn't prevent next-session re-verification -- ✅ **Solution**: Use explicit "DO NOT verify" and "TRUST" directives with counts -- **Example**: "Prerequisites validated" → "DO NOT re-check prerequisites (verified 2x, unchanged)" - -### Pitfall 4: State-Change Paranoia - -- ❌ **Problem**: Assuming files might have changed without evidence -- **Why it happens**: Irrational distrust instead of systematic state tracking -- ✅ **Solution**: Check git status, trust state unless commit/timestamp evidence -- **Example**: "Files might have changed..." → Git shows no commits, trust verified state - -### Pitfall 5: Session Boundary as Re-Verification Trigger - -- ❌ **Problem**: Treating new session as reason to re-verify everything -- **Why it happens**: Not applying cross-session trust protocols -- ✅ **Solution**: Session boundaries don't reset verification—trust persists across sessions -- **Example**: New day ≠ new verification, trust previous session's documented verification - -## Edge Cases - -### Edge Case 1: Long Time Gap (>48 Hours) - -**When**: Multi-day break between sessions makes state change plausible -**Approach**: -- Check git log for commits during gap -- If no commits: Trust verification despite time gap -- If commits exist: Re-verify, document state change evidence -- Update verification count and document justification -**Example**: 3-day weekend gap → Check git, no commits → Trust Friday's verification on Monday - -### Edge Case 2: External Process May Have Modified Files - -**When**: Scripts, CI/CD, or external tools could have changed files -**Approach**: -- Check git status for uncommitted changes -- Review timestamps vs last verification time -- If evidence of change: Re-verify with documented justification -- If no evidence: Trust existing verification -**Example**: CI pipeline runs → Check git for new commits → No commits → Trust verification - -### Edge Case 3: Verification Budget Exhausted But Critical Safety Issue - -**When**: Budget suggests trusting but safety concern requires verification -**Approach**: -- Safety always overrides efficiency when justified -- Document specific safety concern with evidence -- Perform targeted verification (only safety-critical info) -- Update protocols if pattern emerges -**Example**: Production deployment → Justify one-time safety override → Verify critical config → Document as exception - -## Troubleshooting - -| Symptom | Cause | Solution | -|---------|-------|----------| -| Files read 5+ times in one task | Verification budget not applied | Check count before reading, trust after 2-3 verifications | -| Multi-session tasks take 4x expected time | Cross-session verification loops | Apply trust protocol, document "DO NOT verify" directives | -| Agent re-reads despite "DO NOT verify" | Ambiguous summary language | Use explicit directives with counts and rationale | -| Verification waste despite protocols | Summary doesn't document counts | Add verification status section to all summaries | -| State change causes confusion | Not documenting git commit evidence | Check git log, document commit SHA when re-verifying | -| Paralysis from verification paranoia | Distrust without evidence | Trust systematically verified information, check git for evidence | - -## Related Instructions - -- **See also**: [trust_based_task_execution.instructions.md](../trust_execution/trust_based_task_execution.instructions.md) - Trust framework extends to cross-session verification efficiency -- **Prerequisites**: [agentic_decision_making.instructions.md](../agentic_workflows/agentic_decision_making.instructions.md) - Context-first decisions include verification efficiency assessment -- **Integration**: [feature_development.instructions.md](../trust_execution/feature_development.instructions.md) - SC/AC/CV gates create verification points where trust begins - ---- - -**Success Criteria**: Verification operations follow law of diminishing returns with maximum 2-3 verifications per file/prerequisite. Cross-session trust prevents O(N²) waste. Summaries contain explicit "DO NOT verify" and "TRUST" directives. - -**Confidence Check**: Are you about to re-read a file already verified 2+ times? Does the summary document verification counts with explicit directives? Has state actually changed or is this paranoia? diff --git a/.pongogo/path_enforcement_index.json b/.pongogo/path_enforcement_index.json deleted file mode 100644 index 7f19696e..00000000 --- a/.pongogo/path_enforcement_index.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "version": 1, - "entries": [] -} diff --git a/.superpowers/brainstorm/77794-1773363318/.server-info b/.superpowers/brainstorm/77794-1773363318/.server-info deleted file mode 100644 index 9246b9e5..00000000 --- a/.superpowers/brainstorm/77794-1773363318/.server-info +++ /dev/null @@ -1 +0,0 @@ -{"type":"server-started","port":56690,"host":"127.0.0.1","url_host":"localhost","url":"http://localhost:56690","screen_dir":"/Users/shellen/Documents/Claude Stuff/pullread/.superpowers/brainstorm/77794-1773363318"} diff --git a/.superpowers/brainstorm/77794-1773363318/.server.log b/.superpowers/brainstorm/77794-1773363318/.server.log deleted file mode 100644 index fcc3026b..00000000 --- a/.superpowers/brainstorm/77794-1773363318/.server.log +++ /dev/null @@ -1,7 +0,0 @@ -{"type":"server-started","port":56690,"host":"127.0.0.1","url_host":"localhost","url":"http://localhost:56690","screen_dir":"/Users/shellen/Documents/Claude Stuff/pullread/.superpowers/brainstorm/77794-1773363318"} -{"type":"screen-added","file":"/Users/shellen/Documents/Claude Stuff/pullread/.superpowers/brainstorm/77794-1773363318/approaches.html"} -{"source":"user-event","type":"click","text":"B\n \n Unified: Graph + Detail with Adaptive Sidebar\n Two-panel layout: left sidebar (entity list + filters + layer toggle), right is a large persistent graph with detail popovers. The sidebar adapts context — clicking a graph node shows its details inline. Notes appear as distinct node shapes. Highlights boost edge thickness.\n \n Pros\n Graph gets much more space — feels like THE view\n Two panels instead of three reduces cramping\n Detail as popover keeps focus on graph\n Layer toggle (\"All\" / \"My connections\") fits naturally in sidebar\n Notes as distinct nodes feel native, not bolted on\n \n Cons\n Bigger UI change — detail panel becomes popover\n Must handle graph rendering performance carefully\n Popover UX needs to feel solid, not janky","choice":"unified","id":null,"timestamp":1773365441326} -{"source":"user-event","type":"click","text":"B\n \n Unified: Graph + Detail with Adaptive Sidebar\n Two-panel layout: left sidebar (entity list + filters + layer toggle), right is a large persistent graph with detail popovers. The sidebar adapts context — clicking a graph node shows its details inline. Notes appear as distinct node shapes. Highlights boost edge thickness.\n \n Pros\n Graph gets much more space — feels like THE view\n Two panels instead of three reduces cramping\n Detail as popover keeps focus on graph\n Layer toggle (\"All\" / \"My connections\") fits naturally in sidebar\n Notes as distinct nodes feel native, not bolted on\n \n Cons\n Bigger UI change — detail panel becomes popover\n Must handle graph rendering performance carefully\n Popover UX needs to feel solid, not janky","choice":"unified","id":null,"timestamp":1773365441806} -{"type":"screen-added","file":"/Users/shellen/Documents/Claude Stuff/pullread/.superpowers/brainstorm/77794-1773363318/layout-wireframe.html"} -{"type":"screen-added","file":"/Users/shellen/Documents/Claude Stuff/pullread/.superpowers/brainstorm/77794-1773363318/layout-wireframe-v2.html"} -{"type":"screen-added","file":"/Users/shellen/Documents/Claude Stuff/pullread/.superpowers/brainstorm/77794-1773363318/waiting.html"} diff --git a/.superpowers/brainstorm/77794-1773363318/.server.pid b/.superpowers/brainstorm/77794-1773363318/.server.pid deleted file mode 100644 index 46344fa0..00000000 --- a/.superpowers/brainstorm/77794-1773363318/.server.pid +++ /dev/null @@ -1 +0,0 @@ -77800 diff --git a/.superpowers/brainstorm/77794-1773363318/approaches.html b/.superpowers/brainstorm/77794-1773363318/approaches.html deleted file mode 100644 index 9fa0e8d0..00000000 --- a/.superpowers/brainstorm/77794-1773363318/approaches.html +++ /dev/null @@ -1,74 +0,0 @@ -

Three Approaches to Knowledge Graph Evolution

-

How to evolve the Research tab to treat notes, highlights, and articles as distinct data types with a persistent graph panel

- -
-
-
A
-
-

Incremental: Evolve the Current Tab

-

Keep the existing three-panel Research layout. Replace the right panel (currently empty/modal) with a persistent live graph. Add note and highlight extraction to the existing pipeline. Edge weight reflects source type.

-
-

Pros

    -
  • Smallest change — builds on working code
    • -
  • Entity list stays as primary nav (proven usable)
    • -
  • Graph becomes ambient without redesigning the tab
    • -
  • Notes/highlights feed into existing entity + edge schema
    • -
-

Cons

    -
  • Three panels can feel cramped, especially graph
    • -
  • Notes as graph nodes are bolted on, not native
    • -
  • Doesn't address the "database browser" feel
    • -
-
-
-
- -
-
B
-
-

Unified: Graph + Detail with Adaptive Sidebar

-

Two-panel layout: left sidebar (entity list + filters + layer toggle), right is a large persistent graph with detail popovers. The sidebar adapts context — clicking a graph node shows its details inline. Notes appear as distinct node shapes. Highlights boost edge thickness.

-
-

Pros

    -
  • Graph gets much more space — feels like THE view
    • -
  • Two panels instead of three reduces cramping
    • -
  • Detail as popover keeps focus on graph
    • -
  • Layer toggle ("All" / "My connections") fits naturally in sidebar
    • -
  • Notes as distinct nodes feel native, not bolted on
    • -
-

Cons

    -
  • Bigger UI change — detail panel becomes popover
    • -
  • Must handle graph rendering performance carefully
    • -
  • Popover UX needs to feel solid, not janky
    • -
-
-
-
- -
-
C
-
-

Contextual: Graph Appears Everywhere

-

Instead of a dedicated Research tab, embed mini-graphs throughout the app. Article view shows a small entity graph for that article. Notebook shows connections between referenced articles. Home shows a "your attention this week" graph. The Research tab becomes a full-screen version of these contextual graphs.

-
-

Pros

    -
  • Graph becomes ambient — you stumble into insights (Harper's ideal)
    • -
  • Context-sensitive: you see what's relevant where you are
    • -
  • Notes and highlights naturally surface in their own context
    • -
-

Cons

    -
  • Much larger scope — touches every view
    • -
  • Multiple graph instances = performance risk
    • -
  • May feel cluttered if not executed perfectly
    • -
  • Hard to get right incrementally
    • -
-
-
-
-
- -
-

Recommendation: B (Unified)

-

B hits the sweet spot. It gives the graph the prominence Harper advocates without the hairball risk of a graph-only view. The two-panel layout gives the graph breathing room while keeping structured browse accessible. Notes as distinct node shapes and edge weighting from highlights are architecturally clean — they extend the existing PDS schema rather than replacing it. And the layer toggle ("All" / "My connections") is a natural fit for the sidebar.

-

C is the long-term vision but too much scope right now. A is safe but doesn't move the needle on the "database browser" feel. B is the meaningful step forward.

-
diff --git a/.superpowers/brainstorm/77794-1773363318/layout-wireframe-v2.html b/.superpowers/brainstorm/77794-1773363318/layout-wireframe-v2.html deleted file mode 100644 index 94a94ee0..00000000 --- a/.superpowers/brainstorm/77794-1773363318/layout-wireframe-v2.html +++ /dev/null @@ -1,197 +0,0 @@ - - -

Section 1: Research Tab Layout (revised)

-

Muted palette matching existing viewer.css — desaturated badges, softer graph nodes

- -
-
-
Adaptive Sidebar
-
- -
- -
- - -
- All - My links - Notes -
- - -
- person - company - tech - place - event - concept -
- - -
-
-
- OpenAI - company -
- 23 -
-
-
- Sam Altman - person -
- 18 -
-
-
- GPT-4 - tech -
- 12 -
-
-
- EU AI Act - event -
- 7 -
-
-
- AI Safety Research - note -
- 3 links -
-
-
- Anthropic - company -
- 5 -
-
- - -
-
Tensions
-
- +3 / -2   OpenAI -
-
-
-
- -
-
Live Graph
-
- - - - - - - - - - - - - - - - - - - - Sam Altman - - - OpenAI - - - GPT-4 - - - EU AI Act - - - AI Safety - - - Anthropic - - - - AI Safety - Research - - - -
- extracted - your links - note -
- - -
-
-
-
Sam Altman
- person -
- × -
-

CEO of OpenAI. Mentioned in 18 articles across AI policy, product launches, and corporate governance.

-
Mentioned in
-
-
● OpenAI Announces GPT-5
-
● The Case Against AI Consolidation
-
● Senate Hearing on AI Regulation
-
-
View all 18 mentions →
-
-
-
-
- -
-

Changes from v1:

-
    -
  • Type badges — now use color-mix(in srgb, color 12%, bg) matching existing viewer.css
    • -
  • Graph nodes — desaturated to 30-35% mix with background, selected node warmer
    • -
  • Extracted edges — nearly invisible (#3a3a4a) so graph doesn't feel busy
    • -
  • User edges — dark gold (#8a6d20) instead of bright amber — visible but not loud
    • -
  • Note node — outlined rather than filled, blends into the graph background
    • -
  • Sentiment dots — also desaturated via color-mix
    • -
  • Overall — the graph background is slightly darker (#12121e) to let nodes float without needing bright colors
    • -
-
diff --git a/.superpowers/brainstorm/77794-1773363318/layout-wireframe.html b/.superpowers/brainstorm/77794-1773363318/layout-wireframe.html deleted file mode 100644 index c75efa66..00000000 --- a/.superpowers/brainstorm/77794-1773363318/layout-wireframe.html +++ /dev/null @@ -1,172 +0,0 @@ -

Section 1: Research Tab Layout

-

Two-panel layout replacing the current three-panel entity browser

- -
-
-
Left: Adaptive Sidebar (260px)
-
- -
- -
- - -
- All - My links - Notes -
- - -
- person - company - tech - place - event - concept -
- - -
-
-
- OpenAI - company -
- 23 -
-
-
- Sam Altman - person -
- 18 -
-
-
- GPT-4 - tech -
- 12 -
-
-
- EU AI Act - event -
- 7 -
-
-
- 📓 AI Safety Research - note -
- 3 links -
-
-
- Anthropic - company -
- 5 -
-
- - -
-
Tensions
-
- +3 / -2   OpenAI -
-
-
-
- -
-
Right: Live Graph (fills remaining space)
-
- - - - - - - - - - - - - - - - - - - - - Sam Altman - - - OpenAI - - - GPT-4 - - - EU AI Act - - - AI Safety - - - Anthropic - - - - AI Safety - Research - - - -
- extracted - your links - note -
- - -
-
-
-
Sam Altman
- person -
- × -
-

CEO of OpenAI. Mentioned in 18 articles across AI policy, product launches, and corporate governance.

-
Mentioned in
-
-
● OpenAI Announces GPT-5
-
● The Case Against AI Consolidation
-
● Senate Hearing on AI Regulation
-
-
View all 18 mentions →
-
-
-
-
- -
-

Key design decisions in this wireframe:

-
    -
  • Sidebar collapses from 3 panels to 1 — search, filters, layer toggle, entity list, and tensions all stack vertically
    • -
  • Graph fills remaining space — always visible, not hidden behind a modal
    • -
  • Notes are rounded rectangles (not circles) — visually distinct from entity nodes without adding color noise
    • -
  • User-created edges are thick amber, extracted edges are thin gray — weight conveys source at a glance
    • -
  • Highlight-boosted entities get thicker edges from the extraction graph too (e.g., "Anthropic" above)
    • -
  • Entity detail is a popover on node click, not a dedicated panel — keeps graph focus
    • -
  • Clicking entity in sidebar highlights it in graph (and vice versa)
    • -
-
diff --git a/.superpowers/brainstorm/77794-1773363318/waiting.html b/.superpowers/brainstorm/77794-1773363318/waiting.html deleted file mode 100644 index f92c257a..00000000 --- a/.superpowers/brainstorm/77794-1773363318/waiting.html +++ /dev/null @@ -1,3 +0,0 @@ -
-

Continuing in terminal...

-
\ No newline at end of file diff --git a/PLAN-updates-and-onboarding.md b/docs/plans/2026-02-05-updates-and-onboarding-plan.md similarity index 100% rename from PLAN-updates-and-onboarding.md rename to docs/plans/2026-02-05-updates-and-onboarding-plan.md diff --git a/TAURI_MIGRATION_ASSESSMENT.md b/docs/plans/2026-02-11-tauri-migration-assessment.md similarity index 100% rename from TAURI_MIGRATION_ASSESSMENT.md rename to docs/plans/2026-02-11-tauri-migration-assessment.md diff --git a/email-header-b64.txt b/email-header-b64.txt deleted file mode 100644 index e6b95ec5..00000000 --- a/email-header-b64.txt +++ /dev/null @@ -1 +0,0 @@ -data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABLAAAADcCAIAAADvOs+qAAAQAElEQVR4nOzdB3hU1brG8RVCQgqBFEoKqYTeCS10ECmCIgIWFBXBdu16jiIqqEdpAiog2LCA2GiiKL13FAgthJYAqZSQXk25K9kwDHvPTCYhwZj9/908PDvfLlMy3pM339prVc/KSBMAAAAAAP2pLgAAAAAAukQgBAAAAACdIhACAAAAgE4RCAEAAABApwiEAAAAAKBTBEIAAAAA0CkCIQAAAADoFIEQAAAAAHSKQAgAAAAAOkUgBAAAAACdIhACAAAAgE4RCAEAAABApwiEAAAAAKBTBEIAAAAA0CkCIQAAAADoFIEQAAAAAHSKQAgAAAAAOkUgBAAAAACdIhACAAAAgE4RCAEAAABApwiEAAAAAKBTBEIAAAAA0CkCIQAAAADoFIEQAAAAAHSKQAgAAAAAOkUgBAAAAACdIhACAAAAgE4RCAEAAABApwiEAAAAAKBTBEIAAAAA0CkCIQAAAADoFIEQAAAAAHSKQAgAAAAAOkUgBAAAAACdIhACAAAAgE4RCAEAAABApwiEAAAAAKBTBEIAAAAA0CkCIQAAAADoFIEQAAAAAHSKQAgAAAAAOkUgBAAAAACdIhACAAAAgE4RCAEAAABApwiEAAAAAKBTBEIAAAAA0CkCIQAAAADoFIEQAAAAAHSKQAgAAAAAOkUgBAAAAACdIhACAAAAgE4RCAEAAABApwiEAAAAAKBTBEIAAAAA0KlqAgAAFMvKyvp24aJxjz/59TffWn/WkaNHx78+4en/eyY2NlbgXys+IWHa9A8eG/v47t17BADoBh1CALqWl5meEnk8LepkamT431kZorxlX0rIy0q/sWZjW8PB1sHR1sFJbhiqddv38Os/XFQaMhrl5OSI0qtVq1a1av++vzZmZmYuWbrsk3nzEhOvyG/3/fnnmEcfKfEsGQXnzZu/bv0G5dsePXqMeuB+UVYFBQWpqami9FxcXGxtbQXKKuHChQVfff3VV18r37q6uYaGdhEAoA8EQgA6VZCbc2bpl+fXLxeFhaLCFIpCG2GjKuZlmkieNb0DRaXx6WeffzBjpigrX19fP19fb2+vxo0bDx58R/169URllZ+fL0Pdtm3bv1zwVUbG9Z+L8baWDI27d+9evuKXrdu2GddlihZllZyc3LN3X8uPa4Gnp6ePj3f9+vWDGza8/fZ+zZs1EyiJ/OkfPBj226pV3y3+3rielZkpAEA3CIQA9Cj5xOFjn0/JTrwgYMrFixfFTYgupmy/P3nKwAH97713ZLeuXatXr0T/oyOz3O+/r16zdq31GezKlaSflyxZv2FjWFiYKG9Z2dllToNSQjFle/acuYGBgcPvGXbnkMENGjQQuNHly4m//PLL/gMHdu7afTPvOQBUDQRCALqTfOro/ikvCpj3wvPPBQQEhIeHHwwLO336jOWDZW+qUXCwq5trZkbmpUuXDh85ojpgzdp18is4uOG8uXMbNgwSlcCZM5GPjX1clJIMt7+sXCkqhpen5w+Lv9u2fXtExIl9f/5pOah4eLg3b9bcwnseFRU1Y+Ys+fXaq/95bMyYShXF/3HvTZ7822+rBACgGP8LAUBf8nOyjs5/T1Q+6bFnRaVRu3bth0c/pGwnXLgwddp0k79A+/r6Tp86pWPHDjY214fF5uTkHDhwcN369QsXfWd8sAyW/QcO+vjDWUOGDBb/NOeazlJpu0O+vhXbbevUqaP8kht5eXlbtm59+ZX/mnyG777z9sgRw+3t7Q2V3NzcI0eObN22/ZtvF6pOmTZ9xurVa6dPm9qoUbBAMR9vbwEAuMYmKyNNAIBuRHwzK3bLrWsOmLyH0CSbarah0xc51vEUlU96enqbdiHa+sb1a2Uj0dxZZ8+enTxl2sZNm1R1GTUnvvWmcYb8R8TFxR2PiIiKjFqybJnJLuiZUydUFZnTwsIOxcTE7Nm7d8nSZdpTJrw+fuxjY0Q5mT1n7sez56iKYx595M03Jpg7JTk5+csFX83/9DPtrkXfftO1a6hA8c/x0KFD8fEJ4cePf7f4e23q7n97v/nzPhEAoA8EQgA6UpCbs/mJQSZ3ufg3snV0FOUtI/bs32nWzRtZKALueqjh8MdEpdS7bz/DbYGK4OCGa1f/Yfms/Pz8996frGoVSjLSWDOH561RWFj46muvL1+xQlXXBkJjkZGRtw9Qf5bKNxCuWvX7Cy+9rCp+/tn82/r2tXzips2bH3/iKVVRdkSXL10if2oCRrKzs2+7fYDh9ksFgRCArjBkFICOpJ07pS369ru74Yhxtg5OogIc+eTti39us/Jgk0+vkqjl4qKq+Hj7lHiWra2tbAZmZWWp+mkyJbZr17ZtmzaiEpC9yq6hXbSB0LKgoCAPD3dljYoK4uRs4jPp7u5e0nmib58+P//4/b33jzIuyj7YI2MeW7lieZ06HgLXODg4dOncueJuDQWAyo+F6QHoSKomcTm41Wn80PMVlAZLKzXquKhyZNx68cUXtPVnnn0+OTlZVA4utVxE6dWtU1dUViEhIZMmvqUqyj7YWxMnCtzIzc1VAICOEQgB6Ej6+dOqSk2/RqLS+DstNSelAjtO/xTP+vWfevIJVVGGE+1QUpSj0Q892KJ5c1Vx3foNUVFRAgCAawiEAHQkL0s9e0Q1o6kaK4O8dOtuOPy3GTf2MWdnZ1Xxu8WL8/PzBSqG7M0+/fRT2jo5HABgjEAIAKhwbm5uTz/1pKqYmHhlz569AhWm/+39tDlcBsKkpCQBAEAxAiEA4Fbo07u3tvjz0qUCFcbW1rZXr57aenh4FbxbFQBQNgRCAMCt4O3tpS1u3rxFoCJ17tRJW4yJjRUAABQjEAIAboVatWpphy9mZGSkpbEcbgXy9/fTFs+fPy8AAChGIAQA3CINg4K0xYsXLwlUGBcXEytqnI+OFgAAFCMQAgBuEf8Af20xISFBoMLUsK+hLaal0pUFAFxFIASACmWj+t61aevO//uydlBTVb1Q/l9V5+1l4jbCixcvClSYy4mXtUU/P18BAECx6gIAUIFuiHmBd40OuvsRUa1ayBtzwr+YkrBnk2GXjSY6Vj1ZWVnmdl24ePHPfX+mmrmf0Nvbq0f37ra2tib35uTk7N6zJy4u3uReJ0fH3r17ubq6Cl2KiTExf0xwcLCwWl5e3r59f0acOBERceLYsWPRMTH16tVr4OMTEtJ+yOA7AgMDRVkVFBSEHTq0YcPGkydPRcdEx8cnyCs3bdqkcaNGzZs369unT7Vq5fBn69TU1CNHjp6JjDx16tSJkyflq3BwqOHj7SP71bf16dO9e7f09HQBADpGIASAW6G6k3Or/3vbvWWI8q2Nra3/kIfi92zUQw40OHfOxFwmMgPIf196+ZW9e/dZOHfxooVdunQ2uWvpsuUTJ71t4dyHRz80aeJbQpdiYmK0xcDAAGEdGdgmTnz7WHi4cTGq2PYdOz76ePagQQPfmTTJw8NdlIaMgsuWL/9gxszExCvaK69evUZuyz8BTJ062bN+fVFW8i8FP/28ZMbMWRkZGcZ1+a183MNHjvz22yoBALrHkFEAqHAufsGd//elIQ0aFKXBwiJCHyKjorRFLy9P+W/dunUtn2vhVkN39xLSSFxcnNArk/PHBPj7l3hiUlLSWxMnDR9xr3EalMFPNVWsDG99but36PBhYbXIyMiHHn5k/OtvqNKgigyc/QcMkolUlJ78b+qP1WsGDBr8zrv/M06D2nluAQB0CAGgYvn0Htz4oeerVbczvdvGxqYoEBaKqt4qzMvLizYVTuoXt4CmvP/esLuHnj8fvWPHzo2bNonSGDRwwJKffzxz5szx4xGyW6hqB+ncubPntEVvb2/LZ6WkpNw/6sHTp88YKh06hLz6n1dCQkLy8/PDwsLmf/r55i1blF3yDR/98KPLlvzcqFEJI1Fzc3O/XPDVzFkfGiqenp4PjnqgadMmFy5cXPHLL/v3HzA+Xl558pSpP//4gygN+Un7z6uvqbp/99937+PjxgYEBMjtzMzMsLBDE958K5rZVgGAQAgAFSro7jHOPiV1Y2yKo6BNFc+Ely6ZWF7CuZjccHJy6t2rlyge3rl79x7ZQRKl0b5dO/klN155+SXZsLLcetKPs2fPqkZ7Si+9+IK5uzEVOTk5zzz3vHEaHDr0rqmT37e3t5fb8lwZC2fN/GDQ4DsNbVuZ3B5/8qm1q3+vUaOGucvKPu2YseOML9urZ8+ZM6a7ubkp3w6/Z9gbb05cvmKF8VkyIm7dtk0eKaxTUFDw5lsTjdOg/IAt/m5hq5YtDRX5YevaNXTFsiXPvfCi/LAJANA3howCQAUqOQ1eV8U7hCdOntQWhwy+Q1s0d6+gNeRv/7169hIo9ulnn6sq8v159JGHLZwiA9WEN94yjkmtW7WaNmWykgYNatWqNWf2R8YV2W1btOg7c5eNi48f9dDDxmmwaZMmn38235AGJfkQ774zSTuq87PPvxDWKSws/N977y9ZusxQkVdb+vNPxmnQQD70nI8/EgCge3QIAUAtNyXpzNIvEsMP5CTe7IoI1ezsXQIb+w24t15Id6Fv8+Z/qi2OGDFcW7SxsZG/x5d55Gdt19oCxQnNOBop/vPKyzVr1rRw1jffLvxl5UrjimwG2tmZGPAsW7IhIe2NB3lOmTb93ntHyqyoOjI5OXnUg6NV4zPfeXtS9erqX0IcHR0fHPXA5198aVw8evSYsM5HH89eeGMo/ejDmY0bNzJ3vMyEzz/37Ow5cwUA6BgdQgBQO/njvLjta24+DUoFf+emnDx65JO3M+LOCx3bvmOH6vYwUbT4QUNlnKeWg4PZkYc6V5Cfb+WRqlglim/Yu+/ekRZOSUtLk5nKuNL/9n4WFpbo0V39Z47tO3ZqD3v73f+p0uDAAf07dAgRptzWt6+qIv80kJqaKkoSEXFi7ifzjCt33jmkb58+ls96ePRDAgD0jUAIAGpJxw6I8lVQkBoZLvSqsLBw1iwTY/MeHj1aoJSio2OsOezosWPf//CjqvjRrJkW7vGTvlv8vaoxO2rUAxaO7xraRVVZs3atqrJq1e/a1R363367MMPkChbx8WbnmDWYMXOWqvL6+NdKPEs2CUu7ZgYAVDEEQgBQy01NEuUt61LJv9H+u2RkWjukc+OmTYePHFEVZYPIcrcKJmnfSa3w48dHPagO24sXLezYsYOFs5KTk+d/+plxRXYUu4aGWjildevWqsoff6z++++/Dd/m5+fPMJpT1KBjp47CDOO7Cg0SLpTwn8+uXbsNs54qht9zT/3iJS5LFBwcLABAxwiEAKBWmplgrOXi30hULcePR1hzWGRk5IQ33lQVnZ2dP/7oQ+0tZCjRtwsXWViaLy8vT3b57n/gQVWjT6bBEqfqWfTdYtVZox960PJ8pHZ2djI0qooxMdd7mNt37NAu7RAYGOjt5SXMqF3bxC2gubl/C/MKCgqmTpuuKo4adb+wjp+vrwAAHSMQAoBas0detnN2LSFaLgAAEABJREFUEeXHs2v/um1DRdUiw8P+/fstHyND4/2jHtQuAvHZ/HmexcsPogwefmTM5198kZKSYlyUwXvBV18PvvOuSW+/o1qK/buF31ozceuy5StUlT69e5d4lqsmv0WdPWvYXrNmrfaU3r0srSFhY1Pq6XY3bd6sWl1DZs62bdpYebrlWXYAoMrjr7MAoFa7catO73155cif2Tc9r4ytfY1agU3dmrcTVdHzL768YvnSenXranfJTDJv/qcmlz2YNfODUM29Z7CefG+nTZ8hv+Sb2SEkJDIqytwC6088Pk5+mRyEqRIbG6u9SEBAya1yDw8PVSUqMkpcm8pFPjftKd27dxPlasOGjapK794sPQIA1iIQAoAJDm51vXveIWBRQkJCaNfuMnJ07Rpav159e3u7K0lJsTGxGzZtWrXqd+3xrVu1mjP7owYNGgiUB5kMt27bZnLXyBHDn3/uWW9vb2Gdvfv2qSrBwQ0tz0Cj0C7yEX/hgmE7IuKE9pROHc3eQFgGBQUFf6xeoyp26dxJAACsQyAEANyUz7/4UrvCgYrsZY0b+9hTTz6hWt8cFWHC+NfGjn2sVKfs3LlbVWnWrJkV54mc7BxVJT0tzbDt26BBxIkbMuG0qZOdnJxE+TkeEaFdsjKkfXsBALAOgRAAUIH69O59770je/fqSRQsFx4e7pMmTpTvp52dXVpaenxC/J7de9Zt2GC8zOPkqdMSr1x57tlnHB0drbmmbLKt37BBVWzapEmJJxYWFp48dUpVzMrONmzfddedER9cD4SvvPzSiOHDRbnaoVn5UL5F1oySBQAoCIQAgDLq1rVrw4ZBqqJsBnp5eXl61pd8vL351bx8jXn00cF3DFK2ZfKRXy1btBg3buzSZcteGz/BcNhnn3/xx+o1Pyxe5GV+Pk+DmJgYbZMtKCioxBPXrF2nvfMwI/36pZ54fFxoaJddu3bLj0GXzp38/ct//t5NmzerKiwjAQClQiAEALXC/PwLezYmHjuQfaXUiwfaVLOt6RNYv3Of2sEtRJUWHNxw4bdfC9xanc3cHSc7b3Xq1Bk77glDRUa10Y+MWfLTDyVm8qTkZG0xKioqLy/P5NIg+fn5CQkJMg1OnjJVuzc753qH0MbGpnWrVvJLWE12Ha0/WD7Dv/5ST3UbUAGxEwCqMAIhAKhF/booauVCUVZJ4Qej1y9v998Z7i2q8o1MPt4+ArechVUZevfqdf999/7408+Gigx1L7z4com5PdlUIJz+wQz5JUrP389P3ARz0+SYlJqapi363dwTAAC9YR1CAFCL37FW3LSEXesFcGs9++wzqsrOXbt27txl+azkpGRRfkK7lGVNEdnr27J16zPPPmfc5CxRcnKStmhyaXsAgDl0CAFALTflirhpmfHnBXBreXl69urZU9VkmzFzVteuoRZaiympqSbrTZs0seYWRAM7u+pDhgwZ0P92URpnz579ZeWv3//wQ2Jiqf+7S0oyEQgdHRwEAMBqBEIAUHOo65kZHy1uTu3g5gK45YYPv0cVCA8fOXI8IqK5+WUkTMaqqVPeHzlihKhIcfHxH300e9ny5aKsTN79WINACAClwZBRAFALvHO0TfWb+nuZnUstvwEjBXDLdesaqi1u27bdwikm7yHs2bOnqDDp6ekfz57To2dv4zTo6+s7ZfL7C78pxUxFpjuEjgRCACgFOoQAoObZtZ9r45ZXwg9kJ14UpWRTzda5QYBHixBbh/JcfRuwkqura9MmTVTLwa9du+6pJ83em2dnaolIezs7UTE2bd48/vUJxgNEAwMDX3ju2UGDBlYv5R9irlxJEgCAm0MgBAATHOp4eve8QwD/Ql27dVUFwsNHjsjs5O5uev0JN1dXbTErO7vcV5DMz8+f+8m82XPmGirOzs6yKzhwQH9bW1tRenl5edpiTk6uAABYjSGjAABUKR07dNAWj4UfM3e8yYUKc3NyRLlKSkp6/ImnjNOgp6fnsiU/D75jUNnSoOTi4qItlvszB4CqjUAIAECV0qpVS20xLOyQueNdTXUIzU09WjbJyckj73vAeLabtm3brlyxvFGjYHETTPY2s3OyBQDAagRCAACqFC9PTw8Pd1Xx4MEwc8ebjFUxMbGinGRnZz/59P9FRUUZKq1btVq86Ns6dTzEzXGpZaJDePHiJQEAsBr3EAKAWmF+/oU9GxOPHci+kmDN8Q7unnXbdKnXsaeoxl/ZUCmEtG+/bv0G48pf+/cXFBRUM/URNbmSe2xsjCgP8kHHT3jjr7/2GxcnTXrLoTwWh6hVq5a2GBcXJwAAViMQAoBa1K+LolYuLM0ZhxN2rQuMezho2KMC/7R8UxON6E3btm1VgTAjI+Ps2bNBQUHag318vLXFc+fOi1L6ZN783Xv2jBw+fOjQuwzFn35e8ttvq4wPu+/ekW3btDF3kaysLGE1V9NRtnSBMId7DgHoG3/MBgC1+B1rRemV7SyUu4sXS71YSNXTskULbfHYsXCTB7u4uISEtFcV9+77U5SGDHKzPvxo9+49R8OvP0p2dvaHH31kfJizs/PLL71k4TpXrlwRVvPy8tIWw4+Hi9KIj7dqIAAAVFUEQgBQy00pxa+kN3kWyl1cXLzQvebNm2mLB8PM3kbYs0cPVSUqKirhwgVhtV27dysbTo6OhuLPS5YarzcodesaavnWwYuXSrgD8PjxiGH3jHjlP6+KojXoHbVRVj5iXHwpPgPxFg8uLCx88eVX5COePn1GAEBVRCAEADX72u6i9Mp2FspXTk7OmchIoXtubm6+vr6qoupGPmOhXTpri3+Wpkm4/toIVcMcpzJKzf3kE9VhjRs3tnyd/eaf5NUH2rDh8JEjv6xcqUTHLp1NPPNDhw4L62RmZqrWbFQ5d+7cb7+tko+4detWAQBVEYEQANTqd+4jSs+r+wCBCpNt3Y1eO3ftysjIEBCifft2qsqx8PDk5GSTB7dq1UpbXLJ0mbBOXl7eH6vXKNstW14NhAkJCar2oNQouIR1JlavXWf5gEvXWojKzaLaDqG0a9cuYZ0tW7dZPiAxMVHZyMvPFwBQFTGpDACoBY8YV9MnMPNiKabdr+kdUDTLKCrMBeuGL/564/wlivz8AqE/bVq3XrnyV1Xxr/37+912m/Zge3v7IUMGr1r1u3FRpmuZIVs0by5KsnvPHiWHe0r16yvFyMgo7ZF+/n4WrhMdHR1mflyr4vLly8qGMk+pfJnaY77/4cfXx7/m5OQkSvL7779bPiDpWoR2NBoKCwBVCYEQADSqVfPsdrtAZWLN1JEyvfxmKhDGx+vxrkIzrbPdJgOh9NQTT6gCoTR37ifz530iLJLtwalTpyvbd9wxyFCPjDIRCKtZXJrlw49nm6znG3XnDJ8EJaG5urre1rfvxk2bVKesXbtu2LC7hUWHDh9eY6ohafwXBMOUM05OBEIAVRNDRgEAlY5nfU9VJSIiwvIpMpa8/vobJndFnDixZOlSva0uIDt7sl2nKm7avKWwsNDk8c2aNTWOc4p16zcsX7FCWCTbcYbb8Ab2v/6XlJSUFO3BFuaA3b9/v7alqUhLS1U2YmNjjxXPYurs7GxYyfDJJ8ZpT5kx68PMzExhnvzAvPXWJJO7klOuD6xdu+5qYqxbt64AgKqIQAgAKIuCggoch6ldGU/GgN2795g7XnaQJk56+1i42fUGxr/+RsfOoU8+9fS06R/ExJTPkusmmMla5ajA6jvZbGxsBg++Q1WMjo7evGWLuVOee+YZbfG/r463MD1pVFTUjJmzlG2ZP9u1u37jYoC/v/b4XWZ+iLKL+/yLLwszwsOPKxs//PiTstG69fWbHkNCQjp0CFGdkpCQMGeu2d6mTMXvT55i7gOzf/+B3NxcuXHy5CnDpy4oMFAAQFVEIAQAlCxRszpcfEIFjsMMCAjQFj/8+GOTq5ZnZ2e/8t9Xf/p5ibAoIyNjw8ZNn3/x5dxP5ql2Xbp0WXt8iSukR2uCZVp6uig/GekmZse5nFiK1U369+unLX762efmjm/cuNHdQ4dq6yNG3rd6jYllNlet+r1f/4GGWXz+7+mnjEeEBgaZSFBff/1NUlKSqphw4cLoR8bICCe3PTzcmzZpojpg4aLvZK9ywYKv5n/6mVJpdW3qGsNDax9L/qy//uZbbV32BmUalNcU5s2eM3f7jh1jxl7tPcqGpLe3twCAqohACEBHqjs6qyqFebniH1KQZ2IEo61TTVH5JCcnK7+sGzt9+kxExAlRMbStLVHct7lz6LCwQ4cMgx5lZpMto569+xhuHXx83Ljvv1tk4coybAy7W31r2U5Tk1JaXr5CvnbtdKbHjx8X5cfkcgh/rF4trNa2bZtATV9Lvo1ffrnAuCLz2JatW9OL0+zEt94IDm6ovdSzzz0/7J4Ry1es2L9//86du+QVxj3+5AsvXe/pySA3/J5hxqeYa6ndP+rBs2fPKtsyzMtg1n/AoKhrNxx+t3DhggVfaM96+v+emTx1muHbfrf1Nd7bs0cP7XhX6b33J7/62uuyL6p8K9va8skPvfseQ1B89523f1hsIhnK5PnomLGGj/0dgwba2toKAKiKbLIy0gQA6EP0umUnv79hFJmzT0CX978S/4QLuzce/ex944pdzVo95/4iKhMZvU6cODlj5iyT4wxl2+SxMY9279atRYvm5T4Ho4wfh48cMbe3RfPmqWlphl/0FRPGvzZ27GORkZG3D1Bng4dHPzSgf//mzZvVqlXLuC4j5RdfLvh49hztQ4SEtJ8xfZqfn4lZMQ8dPvzqa+NNrlQ+dcr7Q++6y97eXtyE1NTUtevWjTdzS2Tnzp3uGzlSPr0GDRqUeKmDYWGyv6etjxnzqAw5NZ1r/rx0qezaFVUefeTNNybIjbj4+LuH3ZNYmlak9M3XC3p0764qyjxmskcnigNkdnaOKlQv+PLz3r16yY3nXnjxjz/MRl9fX9+N69eqEpr8UY56cLS5z4w8JTMzQ/WiHnpw1DtvT5INw/YdOllereS7hd+GhnYRAFAVEQgB6EhyxOH9U19UFVs+M6l+x17i1srPztw/+cW086eNi+4tQtr99wNRCciW4LcLFx07Fh52KMzKYCA7UU2bNmnWtOmTTzxevXo5TGF9/HjEkLuGWn/8rBkfDB16lyha7eCGQCiD09w5s+vdOCOITLlLli0LDw/fu3ef5cvKINGyZQt/P7+nnnxi6bLlR44elado+6UqMjwEBgT06dO7b59SrGm5afPmDRs2yhduIQkbk4G8mXzHmzSRL7x9u3bmDvtgxkwLw0QNRo4YPnXKZGVb9j/vvf8B61d0fOXll0wO2pRX6D/wjhLfLoVs1j046gFle8+evQ+OftjckYbcqCJbnXcNvdvKT6zM1d98tUCJ7haCq3Rb376ffzZfAEAVRSAEoCMyhm15aoi2Xqth89qNWlSvcWumlS/MSIhOOnbg7/RU1Q7/wQ8Ej3xcVAKT3n7nu45bivoAABAASURBVMXfizKZNnXyiOHDRXnYuGnTE08+XeJhrVu1+mD6NMNAR+NAOHBA/5kzPjBMR2kwfOR9Ja53p9L/9n7r1m8QpbRj+1YvzVSfJsXFxfXoVYr0aEx22/bt2W1ub3Z29n9fG2+h4aZYuuSndm3bGr6Vb+N770/Zuq2EddtlKJ018wNzS1mI4rlDx4x9vMRsOX/eJ/IdNnwrW9O3G40jNTbh9fFjHxtj7jpnz56d8OZbJeb8QYMGTp86xbBQYVJSUq8+t5l8kvLTteDLL9zd3QQAVFGsQwhAR2wdnLx7DIzbvkZVTz0TLr/EP6qanZ13r8GicujUqVPZAqFMJo0aNRLlpGh9ufVrLfx+L9uSD49+aNQD9xv3JA2DV8eOfey1//7H5K1fQYGBpQ2EslUow4/1TTNRPOtmTWdnKw92d3eX2cPK3qBKr56WWtwyD8/5+KOBAwa8PuENk89fZukPZ81s3qyZcTEoKOirBV9s2Lhx0tvvmmvxyQj3v3ffrVPHQ5gXEhKyeeOGyVOm/rJypbmLPP/cc7LVaVy0sbGZPm3Ko2PGqp7wxx/OGjLE0n8mAQEBixctXLny14lvv2Pyxcof4jP/9/Tj48Yaz3/j5ub29YIvnn7mWVV3sVfPnnNmf+Rs9Q8RAP6N6BAC0Jf8nKw9Ex7LTrwgKpkmD7/YoO9dAqbIbpVMJufOnc/Pz5fNHG9vby8vzw4dOsiOlkwO2uPXb9jo6VlfNRElkpOTjxw9eiLixPGIE4mJifXq1WvQwKdb19D27dubfBsVOTk5p8+cOX3q9ImTJ1NSUlLT0lq2aFE0ULVJE8/69YXVwo8fj4iIOHXqtPyys6vu6+fXwMene7euMnmaO+XcuXO//7H60KFDNWu6yCM7d+ksf/DWPZpIT08PDz8un7N80NjYOA8PD/mZkc+6X7/btB1jRcKFC+vWrT969NiVK1fatm0T2qVzmzZtymX8MwBUZgRCALqTfOro/vefF5WJa9M2IeM/FAAAALcWgRCAHiVFhB399P3c5ERRCfj0HtLo/qdtHW7NHYwAAADXEQgB6FReVsbJxZ/E71gj/jn2rh4tn3rDrWlbAQAA8E8gEALQtdzU5LRzJ1MjT8h//868Ff//0KaarbOnn0tAIxf/oi8BAADwzyEQAgAAAIBOMXcWAAAAAOgUgRAAAAAAdIpACAAAAAA6RSAEAAAAAJ0iEAIAAACAThEIAQAAAECnCIQAAAAAoFMEQgAAAADQKQIhAAAAAOgUgRAAAAAAdIpACAAAAAA6RSAEAAAAAJ0iEAIAAACAThEIAQAAAECnCIQAAAAAoFMEQgAAAADQKQIhAAAAAOgUgRAAAAAAdIpACAAAAAA6RSAEAAAAAJ0iEAIAAACAThEIAQAAAECnCIQAAAAAoFMEQgAAAADQKQIhAAAAAOgUgRAAAAAAdIpACAAAAAA6RSAEAAAAAJ0iEAIAAACAThEIAQAAAECnCIQAAAAAoFMEQgAAAADQKQIhAAAAAOgUgRAAAAAAdIpACAAAAAA6RSAEAAAAAJ0iEAIAAACAThEIAQAAAECnqgkAAFA5/P333wIAgFuIDiEAVBH7D4RdunzJmiPr1a3bvl1bw7c7d+1JS09zc3Xt3KmjuVMiI6NOnj4tN3r37OHg4GCoX7x46UBYmLCobevWnp71RUnMXaqmc01vL08vLy9HRwft3oSEC2GHD8uNzh07urm5mryyTFkbN2+RGw2DghoFNzTepbx2ezv73r16VKtm+o+kZ8+eizh5Ulj32m1tbZ2dnFxcXIICA5ydnYUVriQlhYUdvnjpUm5urlKxs7OrU8ejbZvWdevUUR2ckpK6e+9euREUGNi4UbAw80o93N07dgjRPta2HTszMzMdHR179ehuKIYfjzgfHS03uoV2kc/c1HMUaWlpO3fvkRutW7X09vISAICqgkAIAFWE/J1e/tZuzZEyeBgHwuiYGFlJS02zEAhlXJH5RxRHDuNQlJySotQtSEpOtiYQmrvURXEpMipKbvj7+xnHGIVMU8pZaenpZgNhXp5yTM2aNVWBUHntcmPP3n1dQ7uYPP3S5ctleO0Hww7Vrl2rR/du7m5u5o4pLCzctn3HufPR6if899/x8Qnyy8vL87Y+vY2TqkzFyoNmZ2drA2F0dIyyV/4b0r6dKuLm5OTIcCs35BMzrstQrZy1bsOm4cOGmnyqGRmZyjFJSUkEQgCoShgyCgBVRN26dZxvZNilqnu4e4jyZm9v72xGzZpWNcoMatSwd7lGni57bkr93Lnz6zZslCFKVIDTZyJlLhJlYvza5bahLrt5q35ffer0GXMn/v7HGkMadHCoERgY0KplC9n6c3J0VIoyE/7y66qCggLjx1L2pqamad+Ks+fOG7bjExJUe2Nj45SNBj4+wpSMjIw/9x8QAAA9oUMIAFVE966hqspPS5bm5OTKpGGu7VOOunTqGBDgL8pD547qS8mcs2PnLpmLZGaLiY31bdBAVIBNW7aOHD7Mzs5OlJL2tctG3L6//srOzpHbu/fsla3LOh7qEB526LBsbyrbnTp2aNqksfHeqKiz23fukhvp6el/7T8gDzDs8vb2kvFVFLcB69evZ3yW7PQZPYfzPt7exnujY2OVDQs/qePHIwL8/bRDVQEAVRUdQgBAZScjSrdr4zmjo2NExcjLy9u6bYcoDzJxDb1ziKFbuKn4vj5jOTk5h48cVbZlFFSlQSkwMKBN61bKdsSJk7J3Z3xxZeN8zA1vRWpqqvGcNHFxcaprXrxQFBdlx9XD3V2Yt3HTFuOeJACgaiMQAgD+BQIDA5SN+LIO7LRANlGV8BYXHx8ZGSXKQ40aNe4cPKh69aKROLJVqBqPeqa4xSeKZ38x7v4Zk4HQy9NT2T5x8pSh7ln/6g2ZCTcOCjWMF1XOysouYtgrs2JW8bd16pgdMKz0G3Nzc5XmJABADwiEAIB/k4L8fFHeqlWz7du7l7K9c/eezKwsUR6cnZ1bNG+mbJ8onqfU4My12Nm6dUsLV2jbtrWyEVU8Gcy1Z1vNzbVo+pykpGTjg88X345oZ2dnOMt4uhrDDYR+vr5mHk306dVTSbDn5JkxFdWJBQBUKgRCAMC/wMVrd8c516wpKkC9enWVcZuFhYUbN24W5cTQzbtyY3hLvzYEtH69ehZON4ztzLoxo/r6Xr2L8tLly8qGfNrKHYneXp5169RRZuI5d/76HDMx10aQBvibvYFQtkl79bw6j+u27TsNy2AAAKowJpUBABTJys5e+dsqc3szMjKFRfv++uvw0aPaupOjU7/b+oibk5qaunnrNmVbtW5EOerYIUT2xTIzM5OSk48cPdaqZQtx0+rWvTo7S05OjnFdudlPtuOMZyXVks3AGjXsc3JyVTf1yVCn3IIYHR2jTABjmFM0ICBAFC81KSuXLl02nJIQX3SAg0MNk8s5Gvh4ewcFBkZGReXn52/cvGXQgP4CAFClEQgBAFelpKSKssrOzlEm1VRJT88QpXTw0OHT126xKygskFdIT09XvnVydKy4QGhjY9O/X99ffi1KxQfDDvn5+qrW6ysDmehk5JOtNuPpXgzpztnZqcQruLjUyskpynVZWdmGLOfqWluGyby8vLi4eGVJybPXxpT6NihaUiIw0F8GQhnqZNvQ3c1NHqmMg/W8dlOiBV1DO8fFx8mfpsyTJ0+d1q52CACoSgiEAICrLEw+mZqWZhxptGRUc3IyEW+cnBxFKaUV09a9vDy7d+0qKlKtWrVC2rXdfzBMbq/fsHH4PXfLlChujvK+GVZTFMUpUdlQtQ1NMgwWtbe/YT0M2QOMi4+XzUzlW5kM5b8y+ykX9/fz27V7ryhevkIW4+Kv9Q/9S14aRF7htr59fv9jjdzeu+9PH28v4zUtAQBVDIEQAFDE0cFh8B0Dze3ds3efbBZZOL1DSPvyWofQrpiyLXtrsrslN4ICA7t3CxUVr0WL5mfPnU+8ckW21P78a7+5KUCtJJOtsny8/Y3LG8p8KNt3sgsn91rOnJmZmYZTjOt+fr4yEMrT5VOt6eysNAD9/f2UvfINdHFxkY8eExsb0r5dzLUZYhr4eAsryD8NtGrZ4sjRY/L66zZsGjb0TgEAqKKYVAYAULmEdu404p67lS/DPWxnz50z2aI0pCnjJRZUcgxjWQuFNfr26a302SJOnLx48ZK4CQkXrs6F43Rjk63GtVsHDWvTm5Senn41T2puNfT3uzpZaExMrGE20aDAAMMBfsUTz6SkpBYUFChrddSuXcvQnCxRu7ZtZKQUxZn2YNghAQCoogiEAIDKy83N1ce7qKklU81f+w9oDzCMZtSuw24gu2TKhpXjVx0dHbp3vdqN3LRlq9KiLJtT19qqxlFNalB8p58oXuDBwumG1Sa8vNT3/tWoUcPJsejlxMXFKxdxcKhhPLazYVCQsnH+fLSyrn0DnwaiNPr366vkbdkqtBxcAQD/XgRCAECl1qVLJ2Xj1OkzGRnqKWrcXGsrGxeurUuhFR0Te+1gV2GdgAD/Bj5FmS03N1c+riiTHTt3X05MVLaDGwYZ72p0baaWo8fCzTUh5bmG1lzjYBMzu3h5ecl/E69cURaf8Pa6YTioMvGM3PjrwEGl4u9vdgVCk2S87Nypo7JtMo0DAKoAAiEAoFJzdnIyNLt27dmr2uvi4qJMZpOTk7tm3Xrt6X/uP3C5OC/JZpfhFjtr9OzRze7GG/9KRT5uZNTV1efbtG6lZDMDD3f3Oh4eyvb6jZuystTjXbOzs9et36hs165dS9shFEWptejlyN7p1dssgwJUB3gXn6XchVitWjXDI1qvcaPgevXqCgBA1cWkMgCAcnD23Dlt+07h5+er3I1WZh07tJfhqrCwMD4+QXbDlJX3DLqFdpGZShQtXn9p5W+rggIDfXy87e3sYmLjzkdHJxTfPieFtG9n/R10oniRwL69e61dv6HEI6+/dhuRmZWdnpYWF1+05IOyV8YwGQi1Z/Xq1WP5ipXyRckjV6z8tXmzpgH+/jVrOmdkZJ47f152Dg1DVeXTMPm4XkZrSMi4613cMDQWEBBwPvrqdDJ16pQ6DRoefenyX25m3CwAoDIjEAIAyoEMHobsoVLN1rZZ0ybiJtjb27ds0fzI0WOieBymatJL2T0bcHu/dRs2ynCVkpJ6MOyQdhKULp07lWE9vfr16zVt0jjixEnLh1l47fJB5UOb3CU7n3cMGrB23Ya8YoePHFXWmjdma2vbv19fc3Fa5ls3N9ekpKKVJ+rcGJIVyrwy17ZLN17UQL75slm6afNWAQCoihgyCgBVljIjiI2wKemw6webY+itqQ6zZpk+K5fyu36YqeMNoy7T0tJiNfPHyOQmw5XJ5fKK8kz3bubSYImvvWOHEMP6ila+dpninBwdZZIcPmyouTSo8HB3v3vonQEB/iYv5e/nK/fWrWtpxKZyo6MoWmDQxGhYJTFePcD8oiBh+LQSAAABdklEQVQl/nzkowQGBlw7mN8cAKBKscnKSBMAAFQJ6enpFy9eSs/IkBHLwcHB3d1Nhi5R6ckO4eXLickpKTk5OTLB1q5dq26dOjdzByMAAFYiEAIAAACATnEPIQAAAADoFIEQAAAAAHSKQAgAAAAAOkUgBAAAAACdIhACAAAAgE4RCAEAAABApwiEAAAAAKBTBEIAAAAA0CkCIQAAAADoFIEQAAAAAHSKQAgAAAAAOkUgBAAAAACdIhACAAAAgE4RCAEAAABApwiEAAAAAKBTBEIAAAAA0CkCIQAAAADoFIEQAAAAAHSKQAgAAAAAOkUgBAAAAACdIhACAAAAgE4RCAEAAABApwiEAAAAAKBTBEIAAAAA0CkCIQAAAADoFIEQAAAAAHSKQAgAAAAAOkUgBAAAAACdIhACAAAAgE4RCAEAAABApwiEAAAAAKBTBEIAAAAA0CkCIQAAAADoFIEQAAAAAHSKQAgAAAAAOkUgBAAAAACd+n8AAAD//5pxrLAAAAAGSURBVAMAGE6Ott7JF6gAAAAASUVORK5CYII= \ No newline at end of file diff --git a/human-needed.md b/human-needed.md deleted file mode 100644 index 2ac75b21..00000000 --- a/human-needed.md +++ /dev/null @@ -1,64 +0,0 @@ -# Human-Needed: Manual Steps for CI/CD Migration - -Steps that require human action (secrets, account access, or manual verification) to complete the Tauri CI/CD pipeline. - -## Done - -- [x] Generate Tauri updater signing keypair (`bunx @tauri-apps/cli signer generate -w ~/.tauri/keys`) -- [x] Set `TAURI_SIGNING_PRIVATE_KEY` GitHub secret (`gh secret set TAURI_SIGNING_PRIVATE_KEY < ~/.tauri/keys`) -- [x] Set `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` GitHub secret -- [x] Public key added to `src-tauri/tauri.conf.json` updater config - -## To Do - -### Verify Existing Apple Signing Secrets - -The workflow expects these secrets (carried over from the Swift pipeline). Verify they're still set: - -```bash -gh secret list -``` - -Expected secrets: -- `APPLE_CERTIFICATE_BASE64` — base64-encoded .p12 Developer ID certificate -- `APPLE_CERTIFICATE_PASSWORD` — password for the .p12 -- `APPLE_ID` — Apple ID email for notarization -- `APPLE_ID_PASSWORD` — app-specific password for notarization -- `APPLE_TEAM_ID` — Apple Developer Team ID - -If any are missing, use `scripts/setup-signing-secrets.sh` to set them up. - -### Test the CI Pipeline - -1. **Push this branch or open a PR** — should trigger a CI build (unsigned, since PR builds may not have access to secrets) -2. **Verify both matrix legs pass** — `macos-latest` (ARM64) and `macos-13` (Intel) -3. **Check artifacts** — both builds should upload DMG + app artifacts - -### Test a Signed Release - -1. **Merge to main** — should trigger a build + "latest" pre-release update -2. **Verify signing** — download the DMG from the "latest" release, open it, confirm no Gatekeeper warnings -3. **Tag a release** — `git tag v2.0.0 && git push origin v2.0.0` -4. **Verify draft release** — should create a draft GitHub Release with DMGs from both architectures -5. **Publish the release** — manually publish the draft after verifying artifacts -6. **Verify auto-updater** — confirm `latest.json` is attached to the release and the app can find updates - -### Test the Updater End-to-End - -After a tagged release is published: -1. Install an older version of the app -2. Launch it and trigger "Check for Updates" -3. Confirm it finds the update and can download/install it - -### Clean Up (Optional) - -- Delete the old `latest` release tag if it still references the Swift DMG -- Remove `SPARKLE_PRIVATE_KEY` secret if still set (no longer needed) -- Remove `APPLE_CERTIFICATE` secret if it duplicates `APPLE_CERTIFICATE_BASE64` -- Remove `KEYCHAIN_PASSWORD` secret if set (now generated at runtime in CI) -- Remove `APPLE_SIGNING_IDENTITY` secret if set (now hardcoded as "Developer ID Application") -- Remove `APPLE_APP_SPECIFIC_PASSWORD` secret if set (renamed to `APPLE_ID_PASSWORD`) - -### Phase 2: Share Extension (Future) - -The macOS Share Extension (.appex) needs to be built and injected into the Tauri app bundle. This can be done via `beforeBundleCommand` in tauri.conf.json. Tracked separately. diff --git a/src/viewer.test.ts b/src/viewer.test.ts index e660675d..01bc51ec 100644 --- a/src/viewer.test.ts +++ b/src/viewer.test.ts @@ -318,6 +318,21 @@ bookmarked: 2025-01-15T00:00:00Z }); }); +describe('local API hardening', () => { + const viewerSource = readFileSync(join(__dirname, 'viewer.ts'), 'utf-8'); + + test('never sends CORS allow-origin headers — the API must stay same-origin only', () => { + // Access-Control-Allow-Origin on 127.0.0.1:7777 lets ANY website read the + // user's library, notes, and stored SMTP/LLM credentials from the browser. + expect(viewerSource).not.toContain("setHeader('Access-Control-Allow-Origin'"); + }); + + test('settings writes are owner-only (0600) — settings.json holds credentials', () => { + expect(viewerSource).toMatch(/writeFileSync\(path, JSON\.stringify\(data, null, 2\), \{ mode: 0o600 \}\)/); + expect(viewerSource).toMatch(/chmodSync\(path, 0o600\)/); + }); +}); + describe('sync progress', () => { const rootDir = join(__dirname, '..'); diff --git a/src/viewer.ts b/src/viewer.ts index 1e6b2a11..e7ab8c48 100644 --- a/src/viewer.ts +++ b/src/viewer.ts @@ -2,7 +2,7 @@ // ABOUTME: Serves viewer UI and provides API for listing/reading articles import { createServer, IncomingMessage, ServerResponse } from 'http'; -import { readFileSync, readdirSync, statSync, existsSync, writeFileSync, mkdirSync, watch, unlinkSync, copyFileSync } from 'fs'; +import { readFileSync, readdirSync, statSync, existsSync, writeFileSync, mkdirSync, watch, unlinkSync, copyFileSync, chmodSync } from 'fs'; import { join, extname, dirname } from 'path'; import { exec, execFile, execFileSync } from 'child_process'; import { homedir } from 'os'; @@ -644,7 +644,9 @@ function saveJsonFile(path: string, data: unknown): void { if (!existsSync(dir)) { mkdirSync(dir, { recursive: true }); } - writeFileSync(path, JSON.stringify(data, null, 2)); + // Owner-only: settings.json holds SMTP passwords and LLM API keys + writeFileSync(path, JSON.stringify(data, null, 2), { mode: 0o600 }); + try { chmodSync(path, 0o600); } catch {} // mode is ignored when the file already exists } /** Copy bundled classic books into the output directory and tag them */ @@ -845,11 +847,11 @@ export function startViewer(initialOutputPath: string, port = 7777, openBrowser const server = createServer(async (req: IncomingMessage, res: ServerResponse) => { const url = new URL(req.url || '/', `http://localhost:${port}`); - // CORS for local dev - res.setHeader('Access-Control-Allow-Origin', '*'); - res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS'); - res.setHeader('Access-Control-Allow-Headers', 'Content-Type'); - + // No CORS headers — every legitimate client (the Tauri webview and the + // browser UI) is served from this same origin, so cross-origin access is + // only ever another website's JavaScript probing localhost. Answering + // with Access-Control-Allow-Origin would hand any web page the user's + // library, notes, and stored SMTP/LLM credentials. if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); diff --git a/wiki/Home.md b/wiki/Home.md deleted file mode 100644 index 51beeafc..00000000 --- a/wiki/Home.md +++ /dev/null @@ -1,7 +0,0 @@ -# Project Wiki - -This folder is for strategic documentation: - -- **Architecture decisions** - Why things are built the way they are -- **Strategic context** - High-level project direction -- **Onboarding guides** - Help new contributors get started