prd-impact-map
Skill2 starsChanged 4 months agoMITView on GitHub
Map a PRD to affected repos using the service catalog. Reads the PRD and the resolved config/service-catalog*.yaml from <client>-meta, matches PRD capabilities to service descriptions, generates a versioned impact-map artifact locally, and produces a PR-readiness handoff (handoff.forge for open_draft_pr). Publish via /open-draft-pr or orchestrator ForgeClient after authorization — not inside this skill. Run in <client>-meta after PRD validation and before app spec PRs.
In this repository22 other files it gives its agents.
- ground-specSkill
- initiative-feasibilitySkill
- learning-extractSkill
- loop-specSkill
- pre-implementSkill
- purge-initiative-artifacts-appSkill
- spec-draftSkill
- spec-implementation-planSkill
- spec-technical-reviewSkill
- ensure-repo-graphSkill
- post-product-questionsSkill
- prd-codebase-mapSkill
- review-product-questionsSkill
- commit-workspaceSkill
- create-board-ticketsSkill
- open-draft-prSkill
- prd-qualitySkill
- prd-thinkSkill
- purge-initiative-artifacts-metaSkill
- review-findingsSkill
- update-documentsSkill
- validate-requirementsSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 3 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 55
Treat impact-map-* labels as projections.
- Very specific: line 59
No forge mutations in this skill: Do not create a branch, commit, push, PR, comment, review request, or label here.
- Very specific: line 83
Before mapping, search local files/branches and, when gh is configured, open PRs for:
- Distinctive: line 118
Never propose a second PR while identity is unresolved.
- Distinctive: line 152
Stop without GitHub side effects.
- Very specific: line 156
After T5, present readiness and ask whether to publish.
- Very specific: line 172
Before /open-draft-pr (or orchestrator forge), meta_pr and approval fields are pending.
- Distinctive: line 213
Never infer approval from labels alone.
- Very specific: line 254
When the invocation binds handoff_path (orchestrator / AgentRunner baton), also overwrite that path with the same handoff: envelope before …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
PRD impact map
Identify which repos are affected by a PRD and produce an impact map for tech lead confirmation. Do not open spec PRs in app repos — engineering opens those after tech lead confirms the map.
NON-NEGOTIABLE
- Resolve one service catalog under
<client>-meta/config/before reading the PRD. Preferservice-catalog-<org>.yamlwhen org is known (uniquegovernance-<org>.yamlsuffix). Otherwise accept exactly one ofservice-catalog.yamlorservice-catalog-*.yaml. Fail closed on zero or multiple matches. Do not merge catalogs. Never hardcode a tenant org. Understand what each service owns before matching. - Match PRD capabilities to service
descriptionandownsfields semantically — do not rely on keyword matching alone. - Include transitively affected repos via
depends_onchains. If repo B depends on repo A and the PRD touches A, flag B as potentially affected. - Explicitly list repos that are not affected and why — this is as important as the affected list.
- Save the canonical map at
reports_dir/Impact-Map-{INIT-id}.md. A PR comment or label is never the source of truth. Never writeImpact-Map-*-revN.md/*-v2siblings — overwrite the canonical path and bumpmap_revision(seeprayog-skills/references/artifact-write-contract.md). - Increment
map_revisionfor every changed map and record the prior revision plus change reason. Do not edit history to make a revision appear unchanged. If a legacy*-revNsibling exists, migrate into the canonical path and stop writing the sibling (purge siblings only via/purge-initiative-artifacts-metaallowlist — Impact-Map is KEEP). - Mint durable identities H1–H3 per
prayog-skills/references/artifact-write-contract.md: H1source_prd_digest(PRD bytes), H2 onescope_digestper affected repo (canonical payload recipe), H3map_revision. PreferCAP-*/REQ-*in capability lists (legacy free-text orFR-*acceptable until next PRD edit — seeprayog-skills/references/id-conventions.md). A tech-lead approval (G1) is valid only for the exact meta PR head SHA carrying those values. Impact-Map is KEEP through initiative-closure purge; do not treat mid-lane app report digests as map identity. - Treat
impact-map-*labels as projections. If artifact, review, and label disagree, the gate is closed. - A material PRD/map change or tech-lead revocation invalidates approval. Produce a downstream ripple action for every repo already in flight.
- No forge mutations in this skill. Do not create a branch, commit, push,
PR, comment, review request, or label here. Fill
handoff.forgeforopen_draft_prand recommend/open-draft-pr(or orchestrator ForgeClient onprd-pr-action). Seeprayog-skills/references/forge-side-effects.md#content-producers. - Gate labels are a visible workflow projection, not authority. Exactly one
PE gate label may be active:
impact-map-pending,impact-map-lgtm, orimpact-map-blocked.impact-map-revisedandimpact-map-staleare additional invalidation labels and always close the gate.
Inputs
- PRD — (REQUIRED)
prd/INIT-{id}.mdin<client>-meta - Service catalog — (REQUIRED) resolved file under
<client>-meta/config/(service-catalog-<org>.yamlpreferred; else exactly oneservice-catalog.yamlorservice-catalog-*.yaml) - Git state — (REQUIRED) current branch/base, changed files, and whether a meta PR already exists; an existing PR is not required for the initial map
- Meta PR state — (OPTIONAL) URL/head/reviews/labels when revising an open PR
- Prior impact map — (OPTIONAL) required when revising an existing map
- In-flight app artifacts — (OPTIONAL) spec/TDD/plan status for ripple actions
- Layout —
reports_dirfrom.harness/profile.yaml; defaultprd/reports
Initiative identity and PR collision gate
Before mapping, search local files/branches and, when gh is configured, open
PRs for:
- the canonical initiative id,
- legacy/short initiative ids referenced by the PRD or filenames,
- PRD titles/slugs that may represent the same business initiative,
- prior
Impact-Map-*artifacts.
Classify detection separately from the human decision:
| Detection | Meaning | T0 result |
no-collision | No competing initiative/PR found | Continue |
same-initiative | Existing PR/branch represents this product initiative | needs-input |
unrelated | Similar id/title is demonstrably a different initiative | Continue with evidence |
ambiguous | Identity cannot be determined | needs-input |
For same-initiative or ambiguous, the agent may recommend—but never select—
one human resolution:
reconcile-existingsupersede-existingunrelated-confirmed
Persist the distinction in the response:
identity_collision:
detection: same-initiative
evidence: [...]
recommended_resolution: supersede-existing
human_decision: pending
external_action_authorized: falseNever propose a second PR while identity is unresolved. Closing, commenting on, or updating an existing PR is an external action requiring explicit user authorization.
HARD STOP: while human_decision: pending, do not execute T1–T5, assign
impact-map question ids, compute repo scope digests, write/update an impact-map
artifact, or produce PR readiness. Emit only the collision report and a
needs-input workflow handoff.
Choosing a resolution does not by itself authorize GitHub action. Present the exact comment/close/update operations and obtain separate explicit authorization. After reconciliation/supersession is complete, restart at T0; do not resume a partial mapping run.
Process
- T0 Gather and identity gate — PRD, service catalog, local git state,
optional meta PR state, prior map, in-flight app artifacts; run detection
above and continue only for
no-collision, evidencedunrelated, or a fully completed human resolution. Otherwise emitneeds-inputand stop. - T1 Understand — list PRD capability areas (data flows, user actions, integrations, storage, auth, notifications, etc.)
- T2 Match — for each capability, match to service
description+owns; include transitive viadepends_on - T3 Diff and order — compare prior revision; derive build/merge order; classify each repo as added, removed, unchanged, narrowed, widened, or reordered
- T4 Output — write the canonical artifact using references/output-template.md; compute the PRD digest and per-repo scope digests from normalized content
- T5 Verify and hand off — verify artifact completeness; present:
- generated/changed files,
- impact summary and blockers,
- proposed branch, base, Draft PR title/body, reviewers, and initial labels,
PR READYorPR BLOCKEDverdict. Stop without GitHub side effects.
PR readiness (fill handoff.forge — do not open the PR here)
After T5, present readiness and ask whether to publish. On outcome: pass,
next is prd-pr-action (open_draft_pr). Fill handoff.forge with pin
requires at minimum (title, body_path, action: open_draft_pr,
draft: true, apply_labels: [impact-map-pending]). Recommend
/open-draft-pr. Do not run forge mutations inside /prd-impact-map.
See prayog-skills/references/forge-side-effects.md.
Output and approval contract
Generated canonical file:
{reports_dir}/Impact-Map-{INIT-id}.md
Use references/output-template.md.
Before /open-draft-pr (or orchestrator forge), meta_pr and approval fields
are pending. After the authorized forge skill / ForgeClient run, the PR body
contains the impact summary, artifact path, map revision, PRD digest, Gate 1
checklist, and PE review request. Clarification comments may discuss the map,
but decisions must be committed to the PRD/map artifact.
Effective state is derived:
| State | Condition | Engineering gate |
draft | Artifact is being generated or revised | closed |
pending_review | Local artifact is PR-ready or Draft PR awaits matching approval | closed |
approved | Latest tech-lead APPROVED review matches current head SHA and artifact/PRD digests | open for affected repo scopes only |
stale | PRD or map content changed after approval | closed for changed scope |
blocked | Tech lead explicitly revoked or paused | closed |
superseded | A newer map revision exists | permanently closed for old revision |
Labels mirror the effective state. PE controls the Gate 1 label:
impact-map-pending— Draft PR awaits PE decisionimpact-map-lgtm— matching approval existsimpact-map-blocked— PE requests changes or explicitly holds the handoff
Agent/PM invalidation labels:
impact-map-revised— new map revision awaiting reviewimpact-map-stale— source PRD changed after approval
Exactly one of impact-map-pending, impact-map-lgtm, or
impact-map-blocked may be active. impact-map-revised or
impact-map-stale always closes the gate even if impact-map-lgtm was not
removed. Any contradiction fails closed.
PE transitions:
| PE action | Remove | Add | Gate |
| Review starts / new revision | impact-map-lgtm, impact-map-blocked | impact-map-pending | closed |
| Request changes / hold | impact-map-pending, impact-map-lgtm | impact-map-blocked | closed |
| Approve exact current head | impact-map-pending, impact-map-blocked, impact-map-revised, impact-map-stale | impact-map-lgtm | open |
Never infer approval from labels alone; a matching GitHub APPROVED review and current artifact/head values are also required.
Material change and ripple policy
Any scope, capability, contract, dependency-order, affected/deferred status,
or acceptance-meaning change is material. A typo-only edit may retain the map
only when the artifact records material_change: false with a reason; the
current head still requires a matching review under the conservative pilot
policy.
For each prior affected repo, emit one action:
| Change | Required action |
| removed / deferred | hold or close; never run feasibility/TDD/plan |
| added | open after latest approval |
| unchanged scope digest | continue after recording revision check |
| narrowed / widened | re-draft then re-feasibility |
| dependency order changed | re-plan for affected dependents |
| removed scope already merged | human decision: revert, corrective PR, or follow-up initiative |
Approval attestation
The requested GitHub review body is:
Impact map approved
initiative: {INIT-id}
map_revision: {N}
meta_pr_head_sha: {SHA}
prd_digest: {DIGEST}
artifact: {reports_dir}/Impact-Map-{INIT-id}.mdApproval is stale when the latest approved review's commit SHA differs from the current meta PR head SHA or any attested value differs from the artifact.
Workflow handoff
- Append/emit the envelope from
prayog-skills/references/handoff-envelope.mdto the impact-map artifact. Use stageprd-impact-map. - When the invocation binds
handoff_path(orchestrator / AgentRunner baton), also overwrite that path with the samehandoff:envelope before exit. Leaving the baton empty is a failed stage for automated consumers.artifact.pathremains the workspace skill output, not the baton path. Seeprayog-skills/references/handoff-envelope.md(Orchestrator baton). - Derive
next_candidates,human_checkpoint, andexternal_actionfrom pinned rootworkflow.yamlfor(stage: prd-impact-map, outcome)perprayog-skills/references/handoff-envelope.md(Derive from pinned workflow). Sethuman_checkpoint: trueonly when the resolved next node'stypeishuman-checkpoint. Setexternal_action: truewhen next isexternal-action(e.g.prd-pr-actiononpass). - On
pass, fill completehandoff.forgeforopen_draft_prper pinrequires. Recommend/open-draft-pr. Followprayog-skills/references/forge-side-effects.md#content-producers.
Transitions: pinned root workflow.yaml for this stage (SSOT). Human or
agent may run this skill; legality and auto-dispatch follow dispatch +
delivery contract + latest handoff. On pass with signals.pr_ready: true,
the next node is typically prd-pr-action (external-action — explicit auth).
The handoff never authorizes forge mutation. next_candidates never authorize
invoke.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

