Workflow Improvement

Workflow Improvement

When To Use

Use this skill after running a command or completing a short session slice where execution felt slow, confusing, repetitive, or fragile.

This skill focuses on improving the workflow assets (skills, agents, commands, hooks) that were involved, not on feature work itself.

When NOT To Use

• Implementing features - focus on feature work first

Required TodoWrite Items

1. fix-workflow:context-gathered 2. fix-workflow:slice-captured 3. fix-workflow:workflow-recreated 4. fix-workflow:improvements-generated 5. fix-workflow:plan-agreed 6. fix-workflow:changes-implemented 7. fix-workflow:validated 8. fix-workflow:lesson-stored

Step 0: Gather Improvement Context (context-gathered)

Before analyzing the current session, gather existing improvement data:

0.1: Check Skill Execution History

Query memory-palace logs for recent performance issues:

# Recent failures (last 7 days)
/skill-logs --failures-only --last 7d

# Performance metrics for involved plugins
pensive:skill-review --plugin sanctum --recommendations

Capture:

• Skills with stability_gap > 0.3
• Recent failure patterns and error messages
• Performance degradation trends

0.2: Query Knowledge Base

Search for previously captured workflow lessons:

# If memory-palace review-chamber is available
/review-room search "workflow improvement" --room lessons
/review-room search "efficiency" --room patterns

Look for:

• Similar workflow issues from past PRs
• Recurring patterns in workflow failures
• Architectural decisions affecting workflows

0.3: Check Git History

Identify recurring issues through commit patterns:

git log --oneline --grep="improve\|fix\|optimize" --since="30 days ago" \
  -- plugins/sanctum/skills/ plugins/sanctum/commands/

# Look for unstable components (frequent fixes)
git log --oneline --since="30 days ago" --follow \
  -- plugins/sanctum/skills/workflow-improvement/

Extract:

• Components with frequent bug fixes (instability signals)
• Patterns in improvement commit messages
• Recurring issue themes

Output Format:

## Improvement Context

### Skill Performance Issues
- sanctum:workflow-improvement: stability_gap 0.35 (5 failures in 7 days)
- Error pattern: "Missing validation in Step 2"

### Knowledge Base Lessons
- PR #42 lesson: "Workflow validation should happen at start, not end"
- Pattern: Early validation reduces iteration time by 30%

### Git History Insights
- workflow-improvement skill: 8 commits in 30 days (instability signal)
- Recurring theme: "Add missing prerequisite checks"

Step 1: Capture the Session Slice (slice-captured)

Identify the most recent command or session slice in the current context window and capture:

• Trigger: What command / request started it (include the literal /command if present)
• Goal: What "done" meant for the user
• Artifacts touched: Skills, agents, commands, hooks (names + file paths)
• Evidence: Key tool calls / errors / retries that indicate inefficiency
• Context from Step 0: Reference any relevant patterns from improvement context

If the slice is ambiguous, pick the most recent complete attempt and state the exact boundary you chose.

Step 2: Recreate the Workflow (workflow-recreated)

Reconstruct the workflow as a numbered list of 5 to 20 steps, identifying inputs, branch points for decisions, and outputs such as file changes or state modifications. During this reconstruction, identify specific friction points that reduce efficiency. These often include repeated steps or redundant tool calls, as well as missing guardrails where validation occurs too late or prerequisites are unclear. Other common issues are a lack of automation for tasks that should be scripted, and discoverability gaps caused by confusing naming conventions.

Cross-reference with Step 0 context:

• Are friction points matching known failure patterns?
• Do repeated steps align with git history themes?
• Are missing guardrails mentioned in review-chamber lessons?

Step 3: Generate Improvements (improvements-generated)

Generate 3 to 5 distinct improvement approaches and score each on impact, complexity, reversibility, and consistency with existing sanctum patterns. The scoring should specifically address whether the change prevents the recurrence of patterns identified in Step 0. Prioritize improvements that address components with a high stability gap (greater than 0.3) or recurring issues found in the git history. You should also incorporate lessons from the review-chamber and aim to reduce failure modes identified in the skill logs. Prefer small, high-use changes such as tightening a skill's exit criteria, adding missing command options, improving hook guardrails for better observability, or splitting overloaded commands into clearer phases.

Step 4: Agree on a Plan (plan-agreed)

Choose 1 approach and define:

• Acceptance criteria ("substantive difference")
• Files to change
• Validation commands to run
• Out-of-scope items to defer

Keep the plan bounded: aim for ≤ 5 files changed unless the workflow truly spans more.

Step 5: Implement (changes-implemented)

Apply changes following sanctum conventions:

• Keep naming consistent across commands/, agents/, skills/, hooks/
• Prefer documentation-first improvements if ambiguity was the primary issue
• If behavior changes, add/adjust tests in plugins/sanctum/tests/

Step 6: Validate Substantive Improvement (validated)

Validation should include at least 2 of:

• Plugin validators / unit tests passing (targeted)
• Re-running the minimal workflow reproduction with fewer steps or less manual work
• A clear reduction in failure modes (e.g., earlier validation, clearer options)

Record the before/after comparison as metrics, not prose:

• Step count reduction
• Tool call reduction
• Errors avoided (what would have failed before)
• Duration improvement (if measurable)

Metrics Comparison Template

## Validation Results

### Before Improvement
- Step count: 15
- Tool calls: 23
- Failure points: 3
- Duration: ~8 minutes
- Manual interventions: 5

### After Improvement
- Step count: 11 (-4, -27%)
- Tool calls: 17 (-6, -26%)
- Failure points: 0 (-3, -100%)
- Duration: ~5 minutes (-37%)
- Manual interventions: 2 (-3, -60%)

### Verification
[E1] Command: `python3 plugins/sanctum/scripts/test_workflow.py`
Output: All tests passed (0.5s)

[E2] Command: `/validate-plugin sanctum`
Output: No issues found

Step 7: Close the Loop (Store Lessons)

After validation, capture the improvement for future reference:

7.1: Update Git History

Commit with descriptive message that future searches will find:

git add <changed-files>
git commit -m "improve(sanctum): <component> - <specific fix>

Addresses recurring issue: <pattern from Step 0>
Reduces <metric> by <percentage>

Evidence: stability_gap reduced from 0.35 to 0.12

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"

7.2: Post Tooling Learnings to Discussions (Preferred)

Observations about night-market tooling (skill behavior, agent coordination, hook timing, command UX) belong in https://github.com/athola/claude-night-market/discussions, not local memory. Always target the night-market repo regardless of which repo you are currently working in.

# Post to night-market Learnings category
# See fix-pr Step 6.7 for the full GraphQL pattern
# targeting athola/claude-night-market explicitly

Repo-specific learnings stay in the current repo. Tooling

learnings always go to

https://github.com/athola/claude-night-market/discussions

so the framework can improve.

7.3: Capture Lesson in Memory Palace (Optional, Local Only)

If the improvement addresses a repo-specific pattern (not tooling), store it locally:

# Store in review-chamber lessons
/review-room capture --room lessons --title "Workflow: <pattern name>"

7.4: Update Improvement Metrics

Track the improvement's impact:

# Check post-improvement stability
pensive:skill-review --skill sanctum:<component> --recommendations

This creates a feedback loop where future /fix-workflow and /update-plugins runs will reference this lesson.

Record Lessons Learned (decision journal)

If this work involved rework, a failed approach, or a blocker, record it to docs/lessons-learned.md so the insight survives past the session (draft and confirm):

• If leyline is installed, invoke Skill(leyline:decision-journal) and append

a lesson entry (what_happened, what_didnt_work, root_cause, action; set phase to review). Show the draft; append on confirmation.

• Fallback (leyline absent): append to docs/lessons-learned.md using the

in-file ENTRY TEMPLATE; assign the next LL-NNN id.

Supporting Modules

• Auto issue creation - patterns for automatically creating GitHub issues from deferred items

Exit Criteria

• [ ] The session slice is captured with a stated boundary, trigger, goal, and

artifacts touched

• [ ] At least 3 distinct improvement approaches were generated and scored
• [ ] One approach was chosen with acceptance criteria and a bounded file list

(<= 5 files unless justified)

• [ ] Validation records before/after metrics (step count, tool calls, or

failure points), not prose

• [ ] If the slice involved rework, a failed approach, or a blocker, the lesson

is recorded to docs/lessons-learned.md via the decision journal

Troubleshooting

Common Issues

If a command is not found, confirm that all dependencies are installed and accessible in your PATH. For permission errors, check file system permissions and run the command with appropriate privileges. If you encounter unexpected behavior, enable verbose logging using the --verbose flag to capture more detailed execution data.

Automatic Issue Creation for Deferred Items

Reusable patterns for automatically creating GitHub issues when items are classified as deferred, backlog, out-of-scope, or suggestions during workflow execution.

Philosophy

Automatic by Default: When items are explicitly classified as deferred/backlog during any workflow, they should be automatically logged to GitHub issues without requiring a separate flag or manual step. The user is notified of what was created.

When to Use This Module

Include this module in any workflow that:

• Classifies items as "deferred", "backlog", "out-of-scope", or "suggestion"
• Identifies work that should be tracked but not addressed immediately
• Produces improvement recommendations with priority levels

Integration Pattern

Step 1: Collect Deferred Items

During workflow execution, collect deferred items in a structured format:

# Data structure for deferred items
DEFERRED_ITEMS=()

# Add items as they're identified
DEFERRED_ITEMS+=("type:suggestion|title:Improve error messages|source:PR #123|file:auth.py:45|description:Error messages could be more descriptive|labels:enhancement,plugin:sanctum")
DEFERRED_ITEMS+=("type:backlog|title:Add rate limiting|source:PR #123|file:routes.py|description:Consider adding rate limiting to API|labels:enhancement,low-priority")

Step 2: Invoke Auto-Creation

At the end of the workflow (after all analysis is complete), invoke the auto-creation routine:

## Auto-Create GitHub Issues

For each deferred item collected during this workflow:

1. **Check for duplicates** before creating
2. **Create the issue** with proper labels and context
3. **Report what was created** to the user

Step 3: Duplicate Detection

Before creating any issue, check if a similar issue already exists:

# Search for existing issues with similar title
SEARCH_QUERY="$ITEM_TITLE in:title is:issue is:open"
EXISTING=$(gh issue list --search "$SEARCH_QUERY" --json number,title --jq '.[0].number // empty')

if [[ -n "$EXISTING" ]]; then
  echo "Skipping duplicate: Issue #$EXISTING already tracks '$ITEM_TITLE'"
  SKIPPED_ITEMS+=("$ITEM_TITLE (duplicate of #$EXISTING)")
else
  # Proceed with creation
fi

Step 4: Issue Creation Template

create_deferred_issue() {
  local TYPE="$1"      # suggestion, backlog, deferred
  local TITLE="$2"     # Issue title
  local SOURCE="$3"    # Where it came from (PR #X, /update-plugins, etc.)
  local FILE="$4"      # file:line reference (optional)
  local DESC="$5"      # Description
  local LABELS="$6"    # Comma-separated labels

  # Determine prefix based on type
  case "$TYPE" in
    suggestion) PREFIX="[Suggestion]" ;;
    backlog) PREFIX="[Backlog]" ;;
    deferred|out-of-scope) PREFIX="[Deferred]" ;;
    improvement) PREFIX="[Improvement]" ;;
    *) PREFIX="" ;;
  esac

  # Create issue body
  BODY="## Context

Identified during $SOURCE as $TYPE item.

$(if [[ -n "$FILE" ]]; then echo "**Location:** \`$FILE\`"; fi)

## Description

$DESC

## Value

This improvement would enhance the codebase by addressing an identified opportunity.

## Acceptance Criteria

- [ ] Implementation complete
- [ ] Tests added/updated (if applicable)
- [ ] Documentation updated (if applicable)

---
*Auto-created by workflow execution*"

  # Create the issue
  ISSUE_URL=$(gh issue create \
    --title "$PREFIX $TITLE" \
    --body "$BODY" \
    --label "$LABELS" 2>&1)

  if [[ $? -eq 0 ]]; then
    echo "$ISSUE_URL"
  else
    echo "ERROR: $ISSUE_URL"
    return 1
  fi
}

Step 5: Report Created Issues

After all issues are created, report to the user:

### Issues Created (Automatic)

| Type | Title | Issue | Labels |
|------|-------|-------|--------|
| Suggestion | Improve error messages | [#115](url) | enhancement, plugin:sanctum |
| Backlog | Add rate limiting | [#116](url) | enhancement, low-priority |

**Skipped (duplicates):**
- "Fix validation" (duplicate of #42)

Workflow-Specific Integration

For /pr-review

Add to Phase 3 (after triage):

### Auto-Create Issues for Out-of-Scope Items

Items classified as "Suggestion" or "Out-of-Scope" during triage are automatically logged:

1. For each suggestion/out-of-scope item:
   - Check for duplicate issues
   - Create issue with `[Suggestion]` or `[Deferred]` prefix
   - Add labels: `enhancement`, plugin label, priority label
   - Reference the source PR

2. Report created issues in the review summary

For /fix-pr

Add to Step 6.1/6.2 (issue creation is already defined - make it automatic):

### Automatic Issue Creation

**CHANGE: Issue creation for suggestions and deferred items is now AUTOMATIC.**

When items are classified as "Suggestion" or "Deferred" during triage (Step 2):
- Issues are created automatically at the end of Step 6
- No `--create-backlog-issues` flag required
- User is notified of all created issues in the summary

**Skip automatic creation with:** `--no-auto-issues` flag

For /update-plugins

Add to Step 5 (after recommendations):

### Auto-Create Issues for Improvement Recommendations

Items in "Critical" and "Moderate" categories are automatically logged:

1. For each improvement recommendation:
   - Check for duplicate issues
   - Create issue with `[Improvement]` prefix
   - Add labels based on component type and priority
   - Reference the plugin being analyzed

2. "Low Priority" items are reported but not auto-created (stay in backlog docs)

For /fix-workflow

Add to Phase 2 (outcome feedback):

### Auto-Create Issues for Identified Improvements

When retrospective analysis identifies workflow improvements:
- Improvements that can't be implemented immediately → auto-create issue
- Pattern: "[Workflow] <improvement description>"
- Labels: `refactor`, `workflow`, priority based on complexity score

Label Strategy

Always add plugin-specific labels when applicable: plugin:sanctum, plugin:imbue, etc.

Error Handling

# If issue creation fails
if ! ISSUE_URL=$(create_deferred_issue ...); then
  echo "Warning: Failed to create issue for '$TITLE'"
  echo "Error: $ISSUE_URL"
  FAILED_ITEMS+=("$TITLE")
fi

At end of workflow:

### Issue Creation Summary

**Created:** 3 issues
**Skipped (duplicates):** 1
**Failed:** 0

If any failed, manually create using:
\`\`\`bash
gh issue create --title "[Type] Title" --body "..." --label "labels"
\`\`\`

Opting Out

To disable automatic issue creation for a specific workflow run:

# Flag to disable
--no-auto-issues

# Or environment variable
SKIP_AUTO_ISSUES=true /pr-review 123

When disabled, deferred items are still reported but not created as issues:

### Deferred Items (not auto-created)

The following items were identified but not logged to GitHub:
- Suggestion: Improve error messages (auth.py:45)
- Backlog: Add rate limiting (routes.py)

To create issues manually: `/create-issue "Title" --labels "enhancement"`