module-attribution-extractor
Runs the deterministic module-attribution extractor over a prompt and surfaces MD-XXXX drafts through the Decision Pause Contract, as the first half of the Attribution Gate in feature-development planning. Use when planning starts, when a pasted ticket needs a first pass before the inferencer, or when a prompt names a module.
- License 许可
- MIT
- 所属仓库
- Eliyce/paqad-ai
- 最近更新
- 2026-11-13
- Stars
- ★ 8
- Forks
- 0
01 前言 Front Matter
- name
- module-attribution-extractor
- metadata
- { "cacheable": "false", "model_tier": "fast", "paqad-meta": "skill.meta.yaml", "output_format": "markdown" }
- description
- Runs the deterministic module-attribution extractor over a prompt and surfaces MD-XXXX drafts through the Decision Pause Contract, as the first half of the Attribution Gate in feature-development planning. Use when planning starts, when a pasted ticket needs a first pass before the inferencer, or when a prompt names a module.
02 资源文件 8
- 参考文档agents/openai.yaml291 B
- 资产文件assets/templates/packet-collision.md720 B
- 资产文件assets/templates/packet-unknown.md600 B
- 参考文档references/pattern-set.md1.7 KB
- 脚本scripts/extract.sh719 B
- 脚本scripts/filter-by-kind.sh1.3 KB
- 脚本scripts/needs-decision.sh1.2 KB
- 参考文档skill.meta.yaml406 B
03 SKILL.md 正文
What It Does
Applies the framework-owned pattern set (Module: / Component: / Area: / Subsystem: ticket headers; module: <slug>; new module <Name>; in the <name> module) to the prompt. Emits one candidate per distinct slug, classified as exact-match, near-collision (Levenshtein ≤ 2 against an existing slug), or unknown. Multiple modules in a single prompt produce one MD-XXXX draft each (spec AC #9).
Use This When
- Running the Attribution Gate at the start of
feature-development.planning. - A user pastes a ticket and you need a deterministic first pass before invoking the inferencer.
- A user prompt explicitly names a module (
module: billing,Subsystem: Reporting).
Inputs
prompt: required. The user-supplied text (typically a ticket body or feature request).project_root: optional. Used to resolvemodule-map.ymlfor collision detection. Defaults tocwd.- The pattern set itself is closed and lives in
references/pattern-set.md.
Procedure
- Resolve the project root (default
cwd). - Invoke the TS engine via the bundled wrapper:
The wrapper shells out tobash scripts/extract.sh <prompt-file> [project-root]paqad-ai module-decisions extract --project-root <root> --prompt-file <tmp>. Prefer--prompt-file(the wrapper always uses it) so multiline ticket text survives the shell. - Parse the emitted JSON. Each entry in
candidateshas:slug,display_name,kind,collision_with,pattern,excerpt. - If
needs_decisionis empty, the extractor either found nothing or every hit was anexact-match: exit with the literal statusextractor: no-decision-neededso the caller can fall through to the inferencer (the empty case) or continue planning (the exact-match case). - Otherwise, for each candidate in
needs_decision, surface a Decision Pause packet viaAskUserQuestion(or the active adapter's Decision Pause Contract entry point).
Decision Pause Packet Shape
For each candidate that needs a decision, the packet must include:
- Question: the user-visible question. For
unknown:Confirm new module "<display_name>" (slug: <slug>)?. Fornear-collision:"<slug>" is suspiciously close to existing module "<collision_with>"; confirm which one this is. - Header: short tag, e.g.
New module,Slug collision. - Options (2–4):
- Accept new module
<slug>: proceed to atomic apply viasrc/module-decisions/apply.ts. - For near-collision: Use existing
<collision_with>, resolve to the existing slug; mark the draftsuperseded. - Rename: collect a new slug from the user; loop back through
extract. - Reject: mark the draft
rejected; no module-map mutation.
- Accept new module
The packet's selected option drives the state transition. Only an explicit Accept response promotes the MD-XXXX from draft → proposed → accepted. No silent acceptance.
Output Contract
- Zero or more MD-XXXX YAML files written under
.paqad/decisions/module-decisions/<id>.yml(one per candidate that needs a decision). - A
Workflow Statusblock listing what was extracted and what is awaiting the user. - On accepted decisions only:
apply.tsperforms the snapshot → temp-write → rename → record update → events append. Do not writemodule-map.ymlfrom this skill directly. - When the extractor returns no candidates, emit the literal status
extractor: no-decision-neededso the caller can fall through tomodule-attribution-inferencer.
Escalate / Stop Conditions
- Stop and surface the packet if
kind === 'near-collision': never auto-resolve to either side. - Stop if the same slug appears in two different patterns with conflicting display names: ask which name to use.
- Refuse to write any MD-XXXX file if the project has no
.paqad/directory (project is not onboarded).
Scripts
Deterministic plumbing: do not re-derive these in the LLM layer.
scripts/extract.sh <prompt-file> [project-root]: invoke the extractor; prints the JSON report.scripts/needs-decision.sh [report.json|-]: exit 0 if a Decision Pause packet is needed, exit 1 otherwise (withextractor: no-decision-neededon stderr).scripts/filter-by-kind.sh <exact-match|near-collision|unknown> [report.json|-]: filtercandidatesby kind; prints a JSON array.
Assets
assets/templates/packet-unknown.md: Decision Pause packet template for anunknowncandidate.assets/templates/packet-collision.md: Decision Pause packet template for anear-collisioncandidate.
Resources
references/pattern-set.md: bundled pattern reference.runtime/base/skills/module-attribution-extractor/agents/openai.yaml: agent interface metadata.src/module-decisions/extractor.ts: pattern set + classification.src/module-decisions/schema.ts: MD-XXXX state machine.src/module-decisions/apply.ts: atomic apply path (only writer ofmodule-map.yml).- the Decision Pause Contract (in the framework bootstrap): packet semantics.
04 同仓库更多 Skills
sample-skill
Sample bundled skill fixture
processing-invoices
Turns a supplier invoice into one ledger line. Use when a supplier invoice arrives and needs booking.
processing-invoices
Turns a supplier invoice into one ledger line. Use when a supplier invoice arrives and needs booking.
understand-idea
Chat and Claude Code: Step 1 of the discover journey: clarifies the goal, who benefits, success and constraints into the idea block. Use when the journey directs it to step 1, not directly.
size-work
Chat and Claude Code: Suggest a size for a ticket from comparable finished work, as a labelled suggestion the team still owns. Use it when someone asks "how big is this?", "roughly how much work is ABC-12?", or wants a backlog item sized. It finds the team's sizing scale at first use, picks two to five of the closest finished tickets with links, and gives a size or range with the drivers behind it and a confidence of low, medium or high, lowered and explained when the area's documents are template text. Every result is labelled a suggested size, never a date or a commitment. It writes nothing into the size field unless the user says "set it", and it refuses to overwrite an existing size unless the user asks to replace it. Produces the sizing block of the record.
refine-ticket
Chat and Claude Code: Improve one or more existing tracker tickets without losing the author's intent. Use it when someone wants a ticket read, diagnosed and tidied up ("this ticket is vague", "fix up ABC-12", "split this, it's too big"). It reads each ticket in full and snapshots it with its last-updated time, says what is wrong with evidence, and proposes a field-by-field before and after change set limited to summary, description, labels, parent, links and new child tickets on a split. It writes nothing until an explicit "apply it" bound to that exact change set, re-checks the ticket for conflicting edits just before writing, never replaces rich descriptions with plain text, never deletes or closes a ticket, and reads each ticket back after applying. Produces the existing and changes blocks of the record.