Skip to content

P1: Give Every Skill a Declared Interface and Run the Isolation Review #1320

Description

@ptr727

Part of #1311. Priority: next. One pull request for the interface contract and the review findings, then one per skill that changes.

Why

Skills are coupled through step numbers and shared tracked files rather than through interfaces. drive-pr requires local-strict-review, whose pass writes a tracked report, which breaks backlog-burndown's central rule (#1290). Skills cite each other by step number, so a renumbering in one is a defect in three. #1295 asks for a review of every skill against the principle the maintainer stated: tightly coupled internally, loosely integrated with siblings. This sub-issue is that review plus the contract that keeps it true.

Scope

  • Define the interface every SKILL.md declares in its frontmatter or a fixed first section: what it takes (inputs, the seat it expects, the checkout it works in), what it produces (files, GitHub writes, a report shape), what tracked files it may write, and which siblings it depends on, by name and by what it needs from them. skill-lifecycle owns the definition. build_dist.py --check or spec/validate.py fails a skill missing the block or writing a tracked file it did not declare.
  • Run the review Review the skills for isolation: tightly coupled, loosely integrated #1295 describes, one short written finding per skill, posted here before any change: what state has to survive the worker, whether the artifact carrying it merges cleanly under concurrency, and whether the skill's own rule depends on a sibling not doing something.
  • Fix the coupling the review finds, one skill per pull request: step-number references become name-and-purpose references, shared tracked writes move to per-branch or untracked artifacts, and a sibling dependency the skill cannot state in its own interface is removed.
  • Give local_review.py's receipt (in the git directory, never committed) as the reference shape for state a worker keeps.

Rules that bind this task

  • The review is read-only and its output is findings, so each fix is separately reviewable.
  • A skill must work when loaded alone. It may point at a sibling. It may not need the sibling's text to be correct.
  • Regenerate mirrors with python3 scripts/build_dist.py.

Acceptance

  • Every skill carries the interface block and the validator fails one that does not.
  • No skill references a sibling by step number.
  • Two workers running any two skills concurrently on different issues do not write the same tracked file.

Closes #1295. Relates #1290, #1300, #1283, #1287, #1164.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    proseA defect in rule or procedure textskillsAgent skill

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions