AGENT SKILL

pr-shared-extraction

Audits pull requests and packages for general helpers living in workflow-specific code instead of shared_utils, then applies extraction fixes by default in small tested CLs. Use when reviewing PRs for architectural layering, migrating utilities out of cert_fix_queue/theme_dialer_pipeline/skills, auditing "similar offenses", or when the user mentions extraction audit, shared_utils migration, orchestration-only packages, thin wrappers, or layer inversions.

License 许可
MIT
最近更新
2026-11-15
Stars
★ 7
Forks
1

01 前言 Front Matter

name
pr-shared-extraction
description
Audits pull requests and packages for general helpers living in workflow-specific code instead of shared_utils, then applies extraction fixes by default in small tested CLs. Use when reviewing PRs for architectural layering, migrating utilities out of cert_fix_queue/theme_dialer_pipeline/skills, auditing "similar offenses", or when the user mentions extraction audit, shared_utils migration, orchestration-only packages, thin wrappers, or layer inversions.

02 资源文件 2

03 SKILL.md 正文

Shared Extraction Audit

Audit PRs and packages for reusable behavior placed in workflow code. Keep orchestration packages thin and shared_utils canonical.

When to use

  • User points at a PR (e.g. #1954, #1965) and asks for the same review loop
  • A package grew fix_one, _default_*, backup upload, rembg session, or residual gates alongside orchestration
  • Before merge: confirm consumers are adapters, not second implementations

Mode routing

Resolve the first matching mode before the audit steps:

  1. preflight-proposal runs pr-shared-extraction preflight-proposal <pr_number> --base-sha <base_sha> --head-sha <head_sha> --worktree <isolated_worktree> under the shared preflight proposal contract. Record each finding with priority and target.
  2. audit-only is report-only and ends after the findings report.
  3. Normal mode follows the existing audit workflow and applies the prioritized fix band by default.

Target architecture

Layer Holds Examples
shared_utils Reusable actions, I/O, DB flips, inference, constants used by 2+ workflows status_promotion, background_removal, drive_production_backup, stp_filenames
Workflow package Orchestration, CLI, sweep loops, workflow-specific constants only cert_fix_queue/pipeline/queue_run.py, theme_dialer_pipeline compose runners
Skills / scripts Operator entrypoints that delegate to shared_utils No parallel rembg/session stacks

Load-bearing rule: If another package would import it, put it in shared_utils. After the move, every former caller imports the shared symbol and the old module is deleted.

Audit workflow

Register this checklist with update_plan and mark each step complete with evidence:

Shared extraction audit:
- [ ] 1. Scope the PR (base branch, changed packages, stated goal)
- [ ] 2. Map canonical homes already in shared_utils
- [ ] 3. Grep for offense patterns (see reference/offense-taxonomy.md)
- [ ] 4. Write prioritized findings (P0–P3)
- [ ] 5. Apply **Mode routing** after the report
- [ ] 6. Extract in small CLs + move/adjust tests
- [ ] 7. Run scoped pytest, then follow the selected mode's mutation boundary
- [ ] 8. When the mode is `preflight-proposal`, record proposal evidence from the [shared preflight proposal contract](../_shared/pr-loop/preflight-proposal.md) and require downstream owner selection before reapplication

Step 1 — Scope

git fetch origin pull/<N>/head:pr-<N>   # or checkout feature branch
git diff <base>...<head> --stat
git diff <base>...<head> --name-only | rg 'shared_utils|cert_fix_queue|theme_dialer|clean_room|\.claude/skills'

Read the PR summary, then verify what landed correctly before listing offenses.

Step 2 — Search patterns

Run these greps on the PR diff scope:

# Rename-only seams and re-export facades
rg '_default_|def _.*_flipper|def _.*_one\b|promote_one|fix_one|backup_upload' <package> shared_utils
rg '^from shared_utils\..* import \w+$' <package>

# Layer inversions (shared importing consumer)
rg 'from (cert_fix_queue|theme_dialer_pipeline|clean_room_theme_icons)\.' shared_utils/

# Parallel stacks (second session/cache for same concern)
rg 'new_session|lru_cache.*session|rembg\.remove' .claude/skills shared_utils

# Duplicate constants
rg 'ALPHA_CHANNEL_INDEX|RGBA_ALPHA|DEFAULT_.*_PREFIX|ONEUI_STP_BASENAME' --glob '*.py'

# Duplicate test support
rg 'fail_if_called|build_rejected_theme_row|preserve_supplied_alpha' --glob '**/tests/**'

Step 3 — Classify offenses

Use reference/offense-taxonomy.md. Assign priority:

Priority Meaning
P0 Layer inversion or duplicate production stack (must fix before merge)
P1 General helper/constants/tests still in consumer package
P2 Module shape, I/O overlap, monolith size
P3 Stale names, docstrings, test attribute bugs

Step 4 — Report template

## PR #<N> extraction audit

### Done well
- [canonical modules and deletions]

### P0 — …
| Offense | Where | Target module | Tests |
|---------|-------|---------------|-------|

### Suggested fix order
1. …

Fix workflow

Extraction rules

  1. Move behavior — delete the consumer copy; every caller imports the shared symbol
  2. Wire shared APIs at the call site — e.g. db_flipper=promote_theme_to_status with filename_prefix=...
  3. Retarget every caller, then delete the old module — grep the old import path; remove re-export facades
  4. Constants: one source; workflow CLI keeps only workflow-specific names (LEDGER_FILENAME, exit codes)
  5. Tests move with behavior — shared module gets shared tests; orchestration keeps integration tests only
  6. Small CLs — one concern per commit; run scoped pytest after each

Canonical target map (this repo)

Need Home
Theme DB status flip shared_utils/theme_db/status_promotion.py
Account folder ↔ ThemeAccount shared_utils/theme_persistence/account_adapter.py
STP basename parsing shared_utils/vendor_utils/stp_filenames.py
Drive backup upload shared_utils/files/drive_production_backup.py
Timestamp scratch dirs shared_utils/files/timestamp_directory_retention.py
Foreground extraction shared_utils/theme_assets/background_removal.py
Cert fix / promote actions shared_utils/theme_assets/cert_closeout/
Fixed-STP promotion sweep shared_utils/vendor_utils/promote_fixed_stp_sweep.py
Cert queue orchestration only cert_fix_queue/pipeline/ (queue_run) and run_cli

See also .claude/rules/reuse-existing-tooling.md before adding helpers.

Verification

# Package under change (from its directory or shared_utils)
cd shared_utils && python -m pytest path/to/tests -n 0 -q
cd cert_fix_queue && python -m pytest tests/ -n 0 -q

# After moving tests: bump CI collect floor in .github/workflows/standalone-packages-tests.yml if applicable

Provide evidence: pytest output counts, not "should work".

Git / PR

  • Branch: cursor/<topic>-593d or existing PR branch
  • Commit message: Extract <what> from <package> into shared_utils
  • Update PR body: architecture table + test counts

Anti-patterns (flag these)

  • _default_* adapter around a shared_utils function in a consumer module
  • Workflow module that only does from shared_utils... import foo as foo
  • fix_one.py / promote_one.py / promote_run.py / backup_upload.py in orchestration packages
  • shared_utils importing theme_dialer_pipeline or cert_fix_queue
  • Second rembg/BiRefNet session in a skill while background_removal exists
  • Identical tests/support.py in two packages
  • config/constants.py that only aliases extracted helpers

Examples

See reference/examples.md for cert_fix_queue (#1965) and background_removal (#1954) audits.

File index

File Purpose
SKILL.md Hub — architecture, routing, audit checklist, and fix workflow
reference/offense-taxonomy.md Offense signals and priority guide
reference/examples.md Audit examples and fix order
../_shared/pr-loop/preflight-proposal.md Shared isolated proposal mode and evidence record
../_shared/pr-loop/preflight-proposal.contract.test.mjs Cross-skill mode and contract test

04 同仓库更多 Skills

jl-cmd-projects
jl-cmd-projects/claude-dev-env

update

Fast-forwards a local repository's main branch to a remote's main after confirming the repo path and source remote through AskUserQuestion. Use when the user says '/update', 'update main', 'fast-forward main', 'sync main from origin', 'pull latest main into <path>', or 'bring main up to date'.

★ 7
jl-cmd-projects
jl-cmd-projects/claude-dev-env

source-command-sr-loop

Converging cleanup loop: repeat /simplify until clean, then repeat /code-review --fix until clean

★ 7
jl-cmd-projects
jl-cmd-projects/claude-dev-env

skill-builder

Skill lifecycle: classify, scaffold, write via the skill-writer-agent, self-audit, compose sub-skills, polish description triggers, enforce deterministic scripts. Triggers: build a skill, new skill workflow, improve this skill, optimize skill description, skill development lifecycle, skill modularity, skill composition, description trigger catalog, deterministic skill scripts.

★ 7
jl-cmd-projects
jl-cmd-projects/claude-dev-env

session-tidy

Audit, clean, and consolidate session logs in the Obsidian vault. Fixes format drift, resolves orphaned next-steps, updates stale statuses, and generates project rollup summaries. Use when session logs feel cluttered or before starting a new project milestone. Triggers on '/session-tidy', 'tidy sessions', 'clean up session logs', 'session audit'.

★ 7
jl-cmd-projects
jl-cmd-projects/claude-dev-env

session-log

Logs a session report as an HTML page, tracks vault context, extracts decisions, and outputs a /rename command. Use for /session-log, 'journal this session', 'log this work', 'session report', 'summarize/log/record this session', 'save session', 'capture session', or 'document what we did'.

★ 7
jl-cmd-projects
jl-cmd-projects/claude-dev-env

run-claude-dev-env

Build, install, run, and test the claude-dev-env installer. Use when asked to run claude-dev-env, install the Claude Code config into ~/.claude, drive the installer, smoke-test it against a sandbox, or run its test suite.

★ 7