yao-meta-skill/reports/system-model.json

{
  "skill_name": "yao-meta-skill",
  "description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
  "systems_doctrine": "Structure drives behavior: improve the boundary, feedback loops, drift watch, and leverage points before adding weight.",
  "stability": {
    "score": 86,
    "band": "stable-first-pass"
  },
  "boundary_map": {
    "owned_job": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
    "input_boundary": [
      "user-provided workflow notes, prompts, docs, or examples"
    ],
    "output_boundary": "a reusable skill output",
    "non_goals": [
      "one-off adjacent requests that do not match the recurring job",
      "private local material that was not intentionally included"
    ],
    "constraints": [],
    "standards": [],
    "human_judgment_boundary": [
      "Ask one focused clarification when the real job, output, or exclusion boundary is unclear.",
      "Escalate visible tradeoffs when benchmark patterns conflict with local privacy, naming, or governance constraints.",
      "Do not silently broaden the skill into adjacent jobs just because the examples are nearby."
    ],
    "maturity_assumption": "governed"
  },
  "feedback_loops": [
    {
      "name": "Intent boundary loop",
      "signal": "Intent confidence score is 30/100.",
      "response": "Ask only the highest-leverage clarification before adding package weight.",
      "evidence": "reports/intent-confidence.md and reports/intent-dialogue.md"
    },
    {
      "name": "Reference synthesis loop",
      "signal": "Benchmark patterns are useful only after they are abstracted into borrow and avoid guidance.",
      "response": "Borrow one pattern at a time and keep the rest as reviewer-visible evidence.",
      "evidence": "reports/reference-synthesis.md",
      "current_patterns": [
        "Borrow a first-time operator flow that explains itself before it asks for more structure.",
        "Borrow a small hypothesis-test-learn loop so the first revision is evidence-backed.",
        "Borrow the discipline of defining what the skill should not own before growing the package.",
        "Borrow the way it turns a messy workflow into a repeatable operating path.",
        "Borrow the clear execution entrypoints and command structure."
      ]
    },
    {
      "name": "Output quality loop",
      "signal": "Generated output may fail in recurring domain-specific ways.",
      "response": "Apply predicted output-risk families as self-repair checks before final output.",
      "evidence": "reports/output-risk-profile.md",
      "current_risk_families": [
        "Markdown readability",
        "Citation and footnote clutter",
        "Screenshot and visual capture",
        "Code and command safety",
        "Tone and specificity"
      ]
    },
    {
      "name": "Reviewer feedback loop",
      "signal": "Human review catches drift that static checks miss.",
      "response": "Capture lightweight feedback and turn repeated findings into gates or references.",
      "evidence": "reports/review-viewer.html and feedback records"
    },
    {
      "name": "Lifecycle loop",
      "signal": "As reuse grows, the skill needs stronger gates, ownership, and regression evidence.",
      "response": "Promote only when the next gate improves reliability more than context cost.",
      "evidence": "manifest.json, reports/iteration-directions.md, and governance checks"
    }
  ],
  "drift_watch": [
    {
      "name": "Trigger drift",
      "watch_signal": "Users start invoking the skill for adjacent one-off or explanation-only requests.",
      "countermeasure": "Add near-neighbor exclusions and route evals before expanding workflow steps.",
      "cadence": "per trigger or description change"
    },
    {
      "name": "Output drift",
      "watch_signal": "Outputs remain valid but become generic, cluttered, or weakly aligned with the user's domain.",
      "countermeasure": "Refresh output-risk and artifact-design profiles, then add one self-repair check.",
      "cadence": "after the first 3-5 real uses",
      "risk_families": [
        "Markdown readability",
        "Citation and footnote clutter",
        "Screenshot and visual capture",
        "Code and command safety",
        "Tone and specificity"
      ]
    },
    {
      "name": "Reference drift",
      "watch_signal": "Borrowed benchmark patterns no longer fit the local job or add ceremony without payoff.",
      "countermeasure": "Re-run reference synthesis and keep only patterns that improve the current boundary.",
      "cadence": "per material benchmark or product assumption change"
    },
    {
      "name": "Governance drift",
      "watch_signal": "Skill usage becomes team-critical while ownership, review cadence, or rollback evidence stays informal.",
      "countermeasure": "Promote maturity tier and add reviewer-visible lifecycle evidence.",
      "cadence": "monthly"
    }
  ],
  "failure_pattern_map": [
    {
      "family": "Boundary failure",
      "symptom": "The skill handles nearby requests that were never part of the recurring job.",
      "repair": "Narrow the description and add explicit non-goals before adding more execution steps."
    },
    {
      "family": "Feedback gap",
      "symptom": "The skill has rules but no signal telling authors which rule should change after use.",
      "repair": "Turn repeated reviewer feedback into one eval, one reference note, or one self-repair check."
    },
    {
      "family": "Output degradation",
      "symptom": "The result is structurally correct but generic, cluttered, or weakly matched to the user's domain.",
      "repair": "Use output-risk families as pre-final checks.",
      "current_risk_families": [
        "Markdown readability",
        "Citation and footnote clutter",
        "Screenshot and visual capture",
        "Code and command safety",
        "Tone and specificity"
      ]
    },
    {
      "family": "Prompt-behavior mismatch",
      "symptom": "The role, task, and format are copied from a prompt instead of becoming stable skill behavior.",
      "repair": "Convert reusable role/task/format assumptions into workflow, reports, or references.",
      "watch_axes": [
        "Specificity"
      ]
    }
  ],
  "leverage_points": [
    {
      "rank": 1,
      "point": "Clarify the real job boundary",
      "why": "Intent uncertainty creates downstream trigger, output, and governance errors.",
      "move": "Ask one focused question and update intent context before adding assets."
    },
    {
      "rank": 2,
      "point": "Tune the frontmatter description",
      "why": "The description is the highest-leverage routing surface.",
      "move": "Name the recurring job, expected input, output, and strongest non-goal in compact language."
    },
    {
      "rank": 3,
      "point": "Install output self-repair checks",
      "why": "The likely failure families are: Markdown readability, Citation and footnote clutter, Screenshot and visual capture.",
      "move": "Add only the checks that prevent recurring output mistakes."
    },
    {
      "rank": 4,
      "point": "Borrow one pattern, not a whole product",
      "why": "External references improve quality when reduced to structure, not copied as surface style.",
      "move": "Start from: Borrow a first-time operator flow that explains itself before it asks for more structure."
    },
    {
      "rank": 5,
      "point": "Close the lifecycle loop",
      "why": "Team-reused skills need visible ownership, review cadence, and regression evidence.",
      "move": "Keep manifest, review viewer, and iteration directions aligned after each material change."
    }
  ],
  "reviewer_rule": "Reviewer should ask whether the skill's structure will keep producing the desired behavior after repeated real use."
}