AGENT SKILL

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

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 resolve module-map.yml for collision detection. Defaults to cwd.
  • The pattern set itself is closed and lives in references/pattern-set.md.

Procedure

  1. Resolve the project root (default cwd).
  2. Invoke the TS engine via the bundled wrapper:
    bash scripts/extract.sh <prompt-file> [project-root]
    
    The wrapper shells out to 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.
  3. Parse the emitted JSON. Each entry in candidates has: slug, display_name, kind, collision_with, pattern, excerpt.
  4. If needs_decision is empty, the extractor either found nothing or every hit was an exact-match: exit with the literal status extractor: no-decision-needed so the caller can fall through to the inferencer (the empty case) or continue planning (the exact-match case).
  5. Otherwise, for each candidate in needs_decision, surface a Decision Pause packet via AskUserQuestion (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>)?. For near-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 via src/module-decisions/apply.ts.
    • For near-collision: Use existing <collision_with>, resolve to the existing slug; mark the draft superseded.
    • Rename: collect a new slug from the user; loop back through extract.
    • Reject: mark the draft rejected; no module-map mutation.

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 Status block listing what was extracted and what is awaiting the user.
  • On accepted decisions only: apply.ts performs the snapshot → temp-write → rename → record update → events append. Do not write module-map.yml from this skill directly.
  • When the extractor returns no candidates, emit the literal status extractor: no-decision-needed so the caller can fall through to module-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 (with extractor: no-decision-needed on stderr).
  • scripts/filter-by-kind.sh <exact-match|near-collision|unknown> [report.json|-]: filter candidates by kind; prints a JSON array.

Assets

  • assets/templates/packet-unknown.md: Decision Pause packet template for an unknown candidate.
  • assets/templates/packet-collision.md: Decision Pause packet template for a near-collision candidate.

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 of module-map.yml).
  • the Decision Pause Contract (in the framework bootstrap): packet semantics.

04 同仓库更多 Skills

Eliyce
Eliyce/paqad-ai

sample-skill

Sample bundled skill fixture

★ 8
Eliyce
Eliyce/paqad-ai

processing-invoices

Turns a supplier invoice into one ledger line. Use when a supplier invoice arrives and needs booking.

★ 8
Eliyce
Eliyce/paqad-ai

processing-invoices

Turns a supplier invoice into one ledger line. Use when a supplier invoice arrives and needs booking.

★ 8
Eliyce
Eliyce/paqad-ai

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.

★ 8
Eliyce
Eliyce/paqad-ai

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.

★ 8
Eliyce
Eliyce/paqad-ai

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.

★ 8