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
- 参考文档reference/examples.md2.1 KB
- 参考文档reference/offense-taxonomy.md3.4 KB
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:
preflight-proposalrunspr-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.audit-onlyis report-only and ends after the findings report.- 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
- Move behavior — delete the consumer copy; every caller imports the shared symbol
- Wire shared APIs at the call site — e.g.
db_flipper=promote_theme_to_statuswithfilename_prefix=... - Retarget every caller, then delete the old module — grep the old import path; remove re-export facades
- Constants: one source; workflow CLI keeps only workflow-specific names (
LEDGER_FILENAME, exit codes) - Tests move with behavior — shared module gets shared tests; orchestration keeps integration tests only
- 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>-593dor 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.pyin orchestration packagesshared_utilsimportingtheme_dialer_pipelineorcert_fix_queue- Second rembg/BiRefNet session in a skill while
background_removalexists - Identical
tests/support.pyin two packages config/constants.pythat 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
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'.
source-command-sr-loop
Converging cleanup loop: repeat /simplify until clean, then repeat /code-review --fix until clean
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.
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'.
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'.
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.