Index of every page on this site: llms.txt
All skills
mvanhorn avatar

/printing-press-polish

@9e1a8d4
Run it yourself

Polish a generated CLI to pass verification and become publish-ready. Runs diagnostics (dogfood, verify, scorecard, go vet, gosec), automatically fixes all issues (verify failures, static-analysis findings, dead code, descriptions, README, MCP tool quality), reports the before/after delta, and offers to publish. Use after any /printing-press run, or on any CLI in $PRESS_LIBRARY/. Trigger phrases: "polish", "improve the CLI", "fix verify", "make it publish-ready", "clean up the CLI", "get this ready to ship".

Use this Skill: https://skilld.dev/gh/mvanhorn/cli-printing-press/printing-press-polish

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencespii-polish.md

≈2.3k tokens on demand. Your agent reads this file only when SKILL.md points to it.

PII Polish — Customer-PII Gate Playbook

Goal: clear the PII ledger so promote and publish gates pass. Every pending finding is either real PII (replace with a placeholder in source) or a justified non-PII match (accept in the ledger with pre-decision fields).

Scope: Phase 1 detectors are shape-only — order/transaction IDs, card-last-4, email, US phone, ZIP+4, postal-address, and account identifiers under account/party/customer-number keys. ASINs and standalone names are a future detector class pending spec-aware detection work. A passing gate is the floor, not "PII-clean."

cli-printing-press pii-audit <cli-dir>

The audit writes <cli-dir>/.printing-press-pii-polish.json. Promote and publish re-run the audit themselves, so the ledger header is the authority — they refuse if pending findings or gate failures remain.

When polish resolved a manuscripts run directory, run the audit with --manuscripts-dir <run-dir>. That adds only <run-dir>/research.json and <run-dir>/research/*.md to the scan and reports them as .manuscripts/<run-id>/... paths, matching the publish-staged tree.

The accept contract

Every status: "accepted" entry must populate:

  • category — one of attribution, place_name, corporate_name, documentation_example, api_provider_data, synthetic_placeholder, other. The closed enum forces a specific claim about what shape of non-PII this is.
  • evidence_context — quote the surrounding 1-2 lines from the source. Lets a reviewer judge the category claim by reading only the ledger.
  • note — free-form; required only when category is other.
{
  "kind": "email",
  "file": "data.json",
  "line": 17,
  "matched_span": "alice@example.com",
  "status": "accepted",
  "category": "documentation_example",
  "evidence_context": "Inside README's 'Sample request' block, under a code fence demonstrating customer-email; reserved @example.com TLD."
}

If category and evidence_context can't be filled honestly, the finding isn't yet understood. Re-read the source and either fix it or pick a sharper category.

Per-finding decision

For each pending finding, read 1-2 lines on either side of the match and pick one outcome:

Outcome When What to do
Fix in source Real customer value (captured order, sniff response, etc.) Replace with the non-matching placeholder from the table below
category: api_provider_data Vendor's published example (Stripe docs use 4242, support@vendor.com, etc.) Cite vendor docs URL or captured field name in evidence_context
category: documentation_example Example value in README/SKILL prose teaching how a field works Quote the documentation context
category: synthetic_placeholder Already a standards-reserved synthetic (user@example.com, +1-555-01xx, 90210-1234, 1 EXAMPLE WAY) Name the convention in evidence_context
category: other Non-PII shape that matched (request ID, batch ID, version range hitting ZIP regex) Required note names what the value actually is

Replacement placeholders

Use these to avoid re-flagging on the next audit:

Detector Placeholder (does not re-match)
card-last-4 PII_CARD_LAST4_EXAMPLE
email PII_EMAIL_EXAMPLE
phone-us PII_PHONE_EXAMPLE
zip-plus-4 PII_ZIP_EXAMPLE
postal-address PII_ADDRESS_EXAMPLE
account-id PII_ACCOUNT_EXAMPLE

When a downstream consumer (parser, schema validator) needs a valid-shape value, use the standards-reserved synthetics — user@example.com, +1-555-0100, 90210-1234, 1 EXAMPLE WAY — and accept the first audit finding as synthetic_placeholder. Subsequent audits preserve the accept.

Detector-specific notes

  • zip-plus-4 has high false-positive rate. Request IDs, batch IDs, correlation IDs, and version ranges all match the shape. Most pending findings here resolve to category: other with a note naming the actual field, not real PII.
  • postal-address matches Title-Case and ALL-CAPS street names with the common US suffixes. Lowercase real addresses are a known gap.
  • card-last-4 requires a context token (card/visa/ending in/last 4/4+ asterisks/x's). Bare 4-digit numbers don't match.
  • account-id matches an identifier-shaped value (8–17 digits, or 8–34 mixed letters and digits) under an account, party, or customer-number key, including nested account.number and names like digitalAccountIdentifier. Short ids, sequential runs (12345678), all-zero runs, and doc tokens (acct_123, <accountId>, PII_ACCOUNT_EXAMPLE) do not match. Ordinary ids (id, page, userId) do not match.

Special cases

Generated files (DO-NOT-EDIT). Files carrying the // Generated by CLI Printing Press ... DO NOT EDIT. header are wiped on every regen — edits there don't survive. Trace upstream: the captured value came from a manuscript or spec file. Fix it at the source, regenerate, re-run the audit. The finding moves to the upstream file.

Manuscripts (.manuscripts/<runID>/). Highest-risk source — captured browser-sniff content is by construction where customer values entered. Acceptance for manuscript findings requires the explicit evidence_context-cited justification; "captured data" alone is not sufficient. When in doubt, replace the value in the manuscript file directly (it's local working state) and use a hand-authored fixture with synthetic values for any downstream tests.

Generated test fixtures (*_test.go, testdata/). Exempt from the audit by design — generated tests commonly carry standards-reserved or synthetic placeholder values, and rewriting them during polish creates churn without reducing customer-PII risk. Real PII in production code, config, README, and manuscript files remains in scope.

Tooling workspaces (.omc/, .claude/). Exempt from the audit at the CLI root — these are agent orchestration or scratch directories, not shippable printed-CLI content.

Vendor spec files at the CLI root (spec.yaml, spec.yml, spec.json). Exempt from the audit when the CLI was not browser-sniffed — these are the OpenAPI/internal source the operator passed to --spec, and vendor example: blocks (Stripe jenny@example.com, GitHub user-schema example phones) are documentation, not customer PII. The exemption does not apply when .printing-press.json records spec_source: sniffed (any nesting or key spelling) or the root spec itself has a top-level spec_source: sniffed. That spec was built from the printer's own session.

Vendor spec source archived under .manuscripts/. Files anywhere inside a .manuscripts/ subtree whose head bytes match an OpenAPI 2.x/3.x or Swagger 2.0 root-document marker are exempt — the operator archived the vendor's published spec source alongside research, and its example: blocks are documentation. The exemption is content-based, not glob-based, so per-resource subdir basenames like apps/calendars.json or vendor-named files like pushpress-v3.yaml are covered without an allowlist. HARs, session-state.json, hand-edited proofs, and any other non-spec content under .manuscripts/ stays in scope because the marker check fails on them.

Forbidden accept patterns

The binary enforces these via gate failures, not just convention:

  • Identical rationale across 6+ findings — clustered by normalized note + category. If you're stamping the same note repeatedly, fix the source content or file a follow-up to tighten the detector.
  • Wholesale-accept punt — when finding count is ≥ 10 and every finding is accepted with no source-level fixes, the all-accepted-no-fixes gate fires.
  • Empty / placeholder evidence_context — "ctx", "n/a", single chars all pass the TrimSpace check mechanically but PR review will catch them. Quote the file.

Resumability

progress.last_processed_finding_id is an optional checkpoint to update after walking each finding. The audit's next: line uses it to resume mid-walk after a context flush. When absent, the audit resumes from the head.

Finding identity is (file, line, kind, normalized matched-span). Editing a file shifts line numbers — findings get fresh IDs and prior accepts no longer carry forward. This is by design: substantive churn deserves a fresh agent walk. Cosmetic edits (whitespace, case) don't change the ID.

Don't manually mark findings as fixed. A real source fix makes the finding disappear from the next audit; the delta line shows 1 resolved.

End-state checklist

  • cli-printing-press pii-audit <cli-dir> ${PII_ARGS[@]} summary reads no pending findings, no incomplete: block. Outside the polish shell, pass --manuscripts-dir <run-dir> when a manuscripts run was resolved.
  • Every accepted finding has category + evidence_context. category: other also has note.
  • No 6+ accepts share a normalized note + category.
  • Real PII fixes landed in source (git diff).
  • If publishing into a public-library clone, add .printing-press-pii-polish.json to that repo's .gitignore.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning9d3 checks · Risk SAFE
  • Gen Agent Trust Hub9d

    The skill is a developer tool for polishing generated Go-based CLI tools. It performs diagnostics, code fixes, and documentation improvements. All operations are local to the developer's workspace or target a specific trusted repository.

  • Socket9d

    No alerts

  • Snyk9d

    Risk: MEDIUM · 1 issue

Signed by skilld at 9e1a8d4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 19 hours ago.

Activeupdated last week
What it can do
Runs commands Reads files Edits files
context
fork
min-binary-version
4.0.0
created_by
user
All 7 allowed tools
BashReadGlobGrepWriteEditAskUserQuestion

README badge

README badge for mvanhorn/cli-printing-press/printing-press-polish