synth-pr-to-sop

/synth-pr-to-sop

Turn a merged PR into a typed workflow entry. The PR's title becomes the workflow name. The PR description, commits, and review notes become ordered steps. The result is a single markdown file with type: workflow frontmatter that the wiki-maintainer aggregates into a topic page.

When to run

After a PR ships that captures a process worth filing. Examples:

• A PR that updates a deploy runbook
• A PR that documents a new onboarding step
• A PR that codifies a fix-and-followup pattern

Two synthesis paths

The script supports two modes. Pick one before running:

Path A: heuristic (offline, no LLM)

The script extracts headers, bullets, and commit subjects deterministically. Good for PRs that already follow a structured template. Run:

python3 skills/synth-pr-to-sop/synth.py <pr-path> --vault-root <vault>

Path B: Claude Code session is the LLM

You (the operator) run this skill from a Claude Code session. The script first runs the heuristic pass and writes a draft. Then Claude reads the PR markdown directly, refines the steps, owners, and edge cases, and writes the final file. No external LLM API call is made by the script. Claude is the LLM, your hands on the keyboard are the operator. This is the default and recommended path.

Step 1: Locate the PR markdown

Argument can be:

• A single file (e.g. External Inputs/GitHub/myrepo/2026-04-30.md)
• A folder of PR exports (e.g. External Inputs/GitHub/myrepo/)

If a folder, the script walks every .md file and processes each one. Idempotent: re-running on the same PR overwrites the same Meta/Workflows/<sha8>.md.

Step 2: Run the heuristic pass

python3 skills/synth-pr-to-sop/synth.py <pr-path> --vault-root <vault>

Output:

• Meta/Workflows/<sha8>.md (typed workflow file)
• stdout (workflow name + path)

The <sha8> is the first 8 chars of a sha1 of the PR ID. This makes the file deterministic and re-runnable.

Step 3: Refine in-session (optional)

Read the workflow file Claude just wrote. Compare against the source PR. Improve:

• name: make it action-oriented
• steps: split combined steps, name owners
• failure_modes: add what could go wrong
• edge_cases: add atypical inputs

Write back with the Edit tool. Do not change the source_pr_id, sha8, or creationDate fields.

Step 4: Verify

python3 -c "import yaml; yaml.safe_load(open('<vault>/Meta/Workflows/<sha8>.md').read().split('---')[1])"

If the YAML parses, the file is valid.

Frontmatter contract

Every workflow file written by this skill has:

type: workflow
name: <extracted>
steps: [...]
source_pr_id: <pr-id>
sha8: <8-char hash>
memory_class: procedural
creationDate: <iso>
provenance:
  - source_type: github
    source_id: <pr-id>

Optional fields the operator can add: owner, topic, failure_modes, edge_cases, approvals, handoffs.

Entity disambiguation

When Meta/.entity-aliases.json exists (built by scripts/entity-disambiguator.py), this skill consults it during entity extraction. Each detected mention writes both raw_mention and canonical_entity into the entity_mentions frontmatter list, so downstream queries can group variant spellings (ProjectAlpha, Project Alpha, projectalpha) under one canonical form. Operator overrides at Meta/entity-aliases-overrides.json always win. When the index is missing, canonical_entity falls back to the raw mention.

Rules

• Never overwrite a workflow file that has been hand-edited unless --force.
• Never call an external LLM API from the script. The synthesis is operator-driven.
• Keep step descriptions imperative and short.
• The PR markdown is read-only; this skill never writes back to it.
• If the PR has no parseable structure, write a stub with a single step and flag it for refinement.