Skip to content

notque/vexjoy-agent / skills/analysis/data

Data analysis, reference enrichment, and data engineering: pipelines and warehouses, server database design and tuning, SQLite with Peewee.

references/decomposition-prompt.md

View on GitHub
# Reference Decomposition — Headless Prompt

You are running as an autonomous process to improve the toolkit's progressive disclosure architecture. This is the inverse of enrichment: instead of ADDING reference files, you EXTRACT content from bloated SKILL.md and agent files into properly structured reference files.

The goal is to keep agent/skill bodies lean (workflow, phases, routing) while domain knowledge lives in reference files loaded on demand.

## Context

- **Date:** ${DECOMP_DATE}
- **Run ID:** ${DECOMP_RUN_ID}
- **Repository:** ${DECOMP_REPO_DIR}
- **Worktree:** ${DECOMP_WORKTREE}
- **Targets:** ${DECOMP_TARGETS}
- **Max targets:** ${DECOMP_MAX_TARGETS}
- **Dry-run mode:** ${DECOMP_DRY_RUN_MODE}

These targets were identified by the detection script as containing extractable content blocks (catalogs, examples, specs, rosters) that belong in reference files rather than the main body. Each target includes file paths, content types, line ranges, and suggested reference filenames.

## If Dry-Run Mode is "yes"

Only perform the audit analysis. For each target:
1. Read the target file and measure its current line count
2. Identify which content blocks are extractable (catalogs, example tables, failure mode lists, spec sections, rosters)
3. Check for existing reference files that could absorb the content
4. Report what WOULD be decomposed: block types, estimated line counts, suggested reference filenames
5. Report findings only — file creation happens in a later phase

Print a summary and exit.

## If Dry-Run Mode is "no"

### Phase 1: Setup

1. Check for existing open decomposition PRs: `gh pr list --search "decomp/refs" --state open --json number | python3 -c "import json,sys; d=json.load(sys.stdin); print(len(d))"`
2. If 3 or more decomposition PRs are already open, log "Too many open decomposition PRs (>=3), skipping to avoid accumulation" and exit. Decomposition changes are larger than enrichment, so the threshold is lower.
3. Verify you are running inside the worktree path (should contain /tmp/decomp-worktree):
   - Run `pwd` to confirm you're in the worktree path
   - Run `git log --oneline -1` to confirm you're at the expected HEAD
4. Create a feature branch: `git checkout -b decomp/refs-${DECOMP_RUN_ID}`

### Phase 2: Decompose Each Target

Process up to ${DECOMP_MAX_TARGETS} targets from the targets list. For each target:

1. **Save a snapshot** before any modifications:
   ```bash
   cp {path} /tmp/decomp-before-{component}.md
   ```

2. **Read the current file** (SKILL.md or agent body) and note its line count.

3. **Read the detection script output** in the target data to understand what content blocks are extractable: their types, line ranges, and suggested reference filenames.

4. **Read any existing reference files** in the component's `references/` directory to avoid creating duplicates. If a reference file with related content already exists, you will MERGE into it rather than creating a new file.

5. **Read the reference file template** at `skills/analysis/data/references/reference-file-template.md` for the standard structure that new reference files must follow.

6. **For each extractable block**, perform the extraction:

   a. **Determine the reference filename.** Use the detection script's suggestion as a starting point. Follow the naming convention: `{domain}-{topic}.md` (e.g., `go-preferred-patterns.md`, `voice-banned-patterns.md`).

   b. **Check for merge targets.** If a reference file with related content already exists, MERGE into it instead of creating a duplicate. Two files covering the same sub-domain is worse than one longer file.

   c. **Create or update the reference file** with the extracted content. Ensure it follows the reference file template structure: scope header, overview, pattern tables, failure mode catalog, etc. Maximum 500 lines per reference file. If content would exceed 500 lines, split into two reference files covering narrower sub-domains.

   d. **Remove the content from the SKILL.md body.** The content is being MOVED, not copied. Do not leave the original content in place.

   e. **Add a loading table entry** that maps task signals to the new reference file. The loading table tells the agent/skill when to load each reference. Format:
      ```
      | Signal/Task | Reference File | When to Load |
      |-------------|---------------|--------------|
      | {signal pattern} | `references/{filename}` | {condition} |
      ```

7. **Verify retained structure.** After extraction, confirm the SKILL.md still retains these essential sections:
   - Frontmatter (title, description, etc.)
   - Brief overview / purpose statement
   - Phase workflow (if applicable)
   - Loading table (with entries for all reference files, including new ones)
   - Error handling / safety section (if applicable)

8. **Run validation:**
   ```bash
   python3 scripts/validate-decomposition.py --before /tmp/decomp-before-{component}.md --after {path} --refs {refs_dir}/
   ```

9. **Run structural check** (if the validation script exists):
   ```bash
   python3 scripts/validate-references.py --check-size   # skills have no per-skill mode
   ```
   Or for agents: `python3 scripts/validate-references.py --agent {name}`

10. **Run depth audit:**
    ```bash
    python3 scripts/audit-reference-depth.py --skill {name} --verbose
    ```
    Or for agents: `python3 scripts/audit-reference-depth.py --agent {name} --verbose`

### Phase 2.5: Validate Decomposition (Keep-or-Revert Gate)

For each decomposed target, evaluate whether the decomposition is valid:

1. **Run validate-decomposition.py** and check the exit code:

   - **Exit code 0 (PASS):** The decomposition is valid. KEEP all changes for this target.

   - **Exit code 1 (FAIL):** The decomposition has issues.
     - Check the error output. Common fixable issues:
       - Missing loading table entry: add the entry and re-run validation
       - Reference file missing scope header: add the header
     - Attempt to fix the issue, then re-run validation
     - If validation still fails after the fix attempt: REVERT by restoring from the snapshot:
       ```bash
       cp /tmp/decomp-before-{component}.md {path}
       ```
       Remove any reference files that were created for this target.

2. **Check the resulting SKILL.md line count.** If the file is still above 500 lines after decomposition, log a warning:
   ```
   [WARN] {name}: still {N} lines after decomposition (target: <=500)
   ```
   This is a warning, not a failure. Some skills have legitimate large workflows that cannot be decomposed further.

3. **Log the decision** for each target:
   - `[KEEP] {name}: {N} blocks extracted, {before} -> {after} lines`
   - `[REVERT] {name}: validation failed — {reason}`
   - `[SKIP] {name}: {reason}`

### Phase 3: Commit and PR

If any targets were successfully decomposed (KEEP decisions exist):

1. **Stage only modified and created files.** This includes:
   - Modified SKILL.md / agent body files
   - New or updated reference files in `references/` directories
   - Stage only files related to this decomposition

2. **Commit** with a descriptive message:
   ```
   refactor(refs): {component} — extract {N} content blocks into references ({before_lines}->{after_lines} lines)
   ```
   If multiple components were decomposed:
   ```
   refactor(refs): decompose {N} components — extract content blocks into references
   ```

3. **Push:**
   ```bash
   git push -u origin decomp/refs-${DECOMP_RUN_ID}
   ```

4. **Create PR:**
   ```bash
   gh pr create --title "refactor(refs): {component} — extract references ({before}->{after} lines)" --body "$(cat <<'EOF'
   ## Reference Decomposition

   Extracted content blocks from bloated skill/agent bodies into structured reference files.

   ### Changes
   - **{component}**: {before_lines} -> {after_lines} lines ({N} blocks extracted)
     - `references/{filename1}`: {description}
     - `references/{filename2}`: {description}

   ### Validation
   - validate-decomposition.py: PASS
   - validate-references.py: PASS
   - audit-reference-depth.py: Level {N}

   *Automated decomposition run ${DECOMP_RUN_ID}*
   EOF
   )"
   ```

5. **Auto-merge:**
   ```bash
   gh pr merge --squash --auto --delete-branch
   ```

6. Stay in the worktree — the primary checkout owns the main branch.

## Safety Constraints

- **Never modify skill/agent LOGIC.** Only move content and add routing. Workflow phases, gates, and decision points STAY in the SKILL.md. Only catalogs, examples, specs, and rosters move to reference files.
- **Never delete content without first putting it in a reference file.** The operation is MOVE, not DELETE. Every line removed from a SKILL.md must appear in a reference file.
- **Maximum 500 lines per reference file.** Split into narrower sub-domain files if needed.
- **Keep `<!-- DO NOT OPTIMIZE -->` blocks in place.** These blocks are explicitly protected from decomposition.
- **No force-push, no commits to main.** Everything goes through a PR.
- **If anything fails, restore from snapshot and continue with the next target.** One failure should not abort the entire run.
- **Preserve loading table integrity.** Every reference file must have a corresponding loading table entry in the parent skill/agent body.
- **Validation gate is mandatory.** Never skip Phase 2.5, even if the decomposition "looks correct".

## Output

End your session with a summary:

```
=== Reference Decomposition Summary ===
Date: {date}
Targets processed: N/M
  - {name}: {before_lines} -> {after_lines} lines ({N} blocks extracted to {M} reference files)
  - {name}: SKIPPED ({reason})
  - {name}: REVERTED ({reason})
PR: {url or "none (dry-run)"}
===
```
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall