agentleFS
mediajunkiemediajunkie/piper-morgan-product/.claude/skills/discovered-work-capture/SKILL.md

discovered-work-capture

Skill8 starsChanged 11 days agoApache-2.0View on GitHub

Capture discovered work as tracking issues immediately. Use when you notice test failures, bugs, missing features, or technical debt during development. Prevents invisible work and ensures PM can prioritize appropriately.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 6 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Purpose: Ensure all discovered work is captured as tracking issues immediately, preventing invisible work and enabling proper …

    line 14
  2. Distinctive:

    When you discover an issue during development, you don't decide whether it matters—you file it, and PM decides priority.

    line 22
  3. Distinctive:

    After filing, return to your assigned task.

    line 93
  4. Distinctive:

    Before ending your session, your log MUST include:

    line 97
  5. Distinctive:

    If you don't file it now, that context evaporates.

    line 138
  6. Distinctive:

    Before marking your session complete:

    line 148

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

discovered-work-capture

Tracker: GitHub issues (gh issue create). This skill used to say bd create, but the beads CLI isn't installed on Amber; every seat already files via gh (CIO ruling 2026-10-05, from Docs's finding). Note that all seats share one GitHub author, so --author @me doesn't isolate your own filings; search by title prefix instead.

Purpose: Ensure all discovered work is captured as tracking issues immediately, preventing invisible work and enabling proper prioritization.


Core Principle

"Not my problem" is NEVER valid reasoning.

When you discover an issue during development, you don't decide whether it matters—you file it, and PM decides priority. Untracked work is invisible work. Invisible work accumulates into technical debt, surprise failures, and broken user experiences.


Trigger Conditions (When to Use)

You MUST use this skill when you encounter:

  1. Test failures not caused by your current changes
    • You're working on feature X, but test Y fails
    • The failure predates your work
    • File it: gh issue create --title "TEST-FAILURE: [describe]" --body "<what, where, evidence>"
  2. Bugs noticed during development
    • You observe incorrect behavior while testing your work
    • It's not directly related to your current task
    • File it: gh issue create --title "BUG: [describe]" --body "<what, where, evidence>"
  3. Missing features that should exist
    • You expected capability X but it's not implemented
    • You had to work around a gap
    • File it: gh issue create --title "MISSING: [describe]" --body "<what, where, evidence>"
  4. Technical debt observations
    • Code that should be refactored
    • Patterns that don't match conventions
    • Performance concerns
    • File it: gh issue create --title "TECH-DEBT: [describe]" --body "<what, where, evidence>"
  5. Documentation gaps
    • Missing or outdated docs that caused confusion
    • File it: gh issue create --title "DOCS: [describe]" --body "<what, where, evidence>"

Workflow

Step 1: Notice the Issue

During your work, you observe something that isn't right but isn't your current task.

Wrong response: "That's not related to my work, I'll ignore it." Correct response: "I need to file this before continuing."

Step 2: Create the Issue Immediately

# Use bd (beads CLI) to create the issue
gh issue create --title "CATEGORY: Brief description of the issue" --body "<what, where, evidence>"

# Example:
gh issue create --title "TEST-FAILURE: test_user_preferences fails with KeyError on empty config" --body "<what, where, evidence>"

Step 3: Add Context

The issue should include:

  • What you observed
  • Where you observed it (file, line, test name)
  • How you encountered it (what were you doing?)
  • Any error messages or output

Step 4: Link if Relevant

# If discovered while working on another issue:
bd dep add <new-issue> <parent-issue> --type discovered-from

Step 5: Continue Your Work

After filing, return to your assigned task. PM will triage and prioritize the new issue.

Step 6: Session Wrap-up

Before ending your session, your log MUST include:

### Discovered Issues Filed
- #XXX: TEST-FAILURE: [description]
- #YYY: BUG: [description]
- (or "None" if no discoveries)

Anti-Patterns

Anti-PatternWhy It's WrongCorrection
"I'll file it later"Later never comes; context is lostFile NOW, takes 30 seconds
"It's not blocking me"Blocking YOU isn't the criteriaPM decides priority
"Someone else will notice"They might not; you noticed NOWYou file it NOW
"It's too small to track"Small issues compoundFile it; PM can close as won't-fix
"I'll just fix it quickly"Scope creep; unplanned workFile first, then ask PM if you should fix
"Not my area"Ownership doesn't matter for filingFile it; correct owner will be assigned

Why This Matters

The Invisible Work Problem

Work that isn't tracked:

  • Doesn't get prioritized
  • Doesn't get resources
  • Doesn't get credit when fixed
  • Compounds until it causes an outage or user complaint

The Discovery Advantage

You noticed something because you were in the code. That context is valuable:

  • You know what you were doing when you found it
  • You can describe the symptoms accurately
  • You have the error messages fresh

If you don't file it now, that context evaporates.

The Priority Fallacy

"I shouldn't file this because it's not important" is a priority decision. You don't make priority decisions. PM does. Your job is to surface the work. PM decides when (or if) it gets done.


Session Wrap-up Checklist

Before marking your session complete:

  • Review work done for any discovered issues
  • All discoveries filed with gh issue create
  • Session log includes "Discovered Issues Filed" section
  • If no discoveries: explicitly state "None" (proves you checked)

Quick Reference

# Create discovered issue
gh issue create --title "CATEGORY: Description" --body "<what, where, evidence>"

# Categories
TEST-FAILURE:  # Test that fails unexpectedly
BUG:           # Incorrect behavior observed
MISSING:       # Expected capability not present
TECH-DEBT:     # Code that needs improvement
DOCS:          # Documentation gap or error

# Link to parent work
bd dep add <new> <parent> --type discovered-from

# List your filed issues
gh issue list --search "in:title CATEGORY:" --state open

Skill created: January 26, 2026 Per CIO approval of Simple Trigger Architecture

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.