feat: add authoring discipline guardrails

2026-04-25 15:58:43 +08:00
parent 6a46d57cef
commit 13a67da51e
8 changed files with 133 additions and 7 deletions
@@ -243,6 +243,7 @@ The repository now treats method as a first-class asset instead of scattered gui
 - [Skill Engineering Method](references/skill-engineering-method.md)
 - [Intent Dialogue](references/intent-dialogue.md)
 - [Reference Scan Strategy](references/reference-scan.md)
+- [Authoring Discipline](references/authoring-discipline.md)
 - [Skill Archetypes](references/skill-archetypes.md)
 - [Gate Selection](references/gate-selection.md)
 - [Iteration Philosophy](references/iteration-philosophy.md)
@@ -23,7 +23,7 @@ Build reusable skill packages, not long prompts.
 - `Production`: team reuse with focused gates.
 - `Library`: shared infrastructure or meta skill.

-Mode rules: [Operating Modes](references/operating-modes.md), [QA Ladder](references/qa-ladder.md), [Resource Boundaries](references/resource-boundaries.md), [Method](references/skill-engineering-method.md).
+Mode rules: [Method](references/skill-engineering-method.md), [Operating Modes](references/operating-modes.md), [Resource Boundaries](references/resource-boundaries.md), [Authoring Discipline](references/authoring-discipline.md).

 ## Compact Workflow

@@ -34,7 +34,7 @@ Mode rules: [Operating Modes](references/operating-modes.md), [QA Ladder](refere
 5. Add only the folders and gates that earn their keep.
 6. After the first package exists, surface the top three next iteration directions.

-Core playbooks: [Method](references/skill-engineering-method.md), [Intent Dialogue](references/intent-dialogue.md), [Reference Scan](references/reference-scan.md), [Archetypes](references/skill-archetypes.md), [Gate Selection](references/gate-selection.md), [Iteration Philosophy](references/iteration-philosophy.md), [Non-Skill Decision Tree](references/non-skill-decision-tree.md).
+Core playbooks: [Method](references/skill-engineering-method.md), [Intent Dialogue](references/intent-dialogue.md), [Reference Scan](references/reference-scan.md), [Authoring Discipline](references/authoring-discipline.md).

 ## First-Turn Style

@@ -62,4 +62,4 @@ Unless the user asks otherwise, produce:

 ## Reference Map

-Primary references: [Method](references/skill-engineering-method.md), [Reference Scan](references/reference-scan.md), [Intent Dialogue](references/intent-dialogue.md), [Governance](references/governance.md), [Resource Boundaries](references/resource-boundaries.md).
+Primary references: [Method](references/skill-engineering-method.md), [Authoring Discipline](references/authoring-discipline.md), [Reference Scan](references/reference-scan.md), [Intent Dialogue](references/intent-dialogue.md), [Governance](references/governance.md), [Resource Boundaries](references/resource-boundaries.md).
@@ -0,0 +1,74 @@
+# Authoring Discipline
+
+Use this discipline when creating, refactoring, or reviewing a skill package. It keeps the system useful without turning every request into a heavy framework.
+
+## Principle
+
+Every added instruction, file, script, evaluation, or governance rule must trace back to the user's real recurring job.
+
+## 1. Assumption Discipline
+
+Do not deepen the package on a guessed goal.
+
+- state the working assumption when the user's request has more than one plausible interpretation
+- ask a short follow-up when the recurring job, target output, or exclusion boundary is unclear
+- surface a real design conflict instead of silently choosing a risky direction
+- proceed silently only when the decision is low-risk and reversible
+
+Good clarification is small. Ask the question that changes the package design, not a full intake form.
+
+## 2. Scope Discipline
+
+Build the smallest reliable package.
+
+- do not add features the user did not ask for or the workflow does not need
+- do not add generic configurability before a real variation exists
+- do not add empty folders, decorative reports, or broad policy text to look complete
+- prefer one strong execution path over several speculative branches
+
+A package is not better because it has more files. It is better when the recurring job becomes clearer, safer, or easier to verify.
+
+## 3. Change Discipline
+
+When improving an existing skill, make surgical changes.
+
+- touch only files that directly support the requested change
+- match the existing style and structure unless they are the problem
+- remove unused artifacts created by the current change
+- mention unrelated dead code or drift, but do not clean it up unless asked
+
+The review test: every changed line should explain which user goal, boundary, or verification need it serves.
+
+## 4. Verification Discipline
+
+Tie each meaningful change to a check.
+
+- trigger changes need route or near-neighbor evidence
+- execution changes need a sample input, script check, or manual run note
+- new references need a reason they reduce ambiguity or context cost
+- new governance needs an owner, lifecycle expectation, or review cadence
+- new packaging or portability claims need a concrete target or compatibility check
+
+If a change cannot be verified yet, label it as a candidate next step instead of shipping it as part of the baseline package.
+
+## Reviewer Checklist
+
+Before approving a generated or modified skill, check:
+
+- the real recurring job is explicit
+- unresolved assumptions are named or clarified
+- the package is no larger than the job requires
+- changes are limited to the requested scope
+- each new artifact has a verification reason
+- the next iteration direction is focused, not a bundle of speculative upgrades
+
+## Failure Patterns
+
+Treat these as authoring failures:
+
+- creating a skill for a one-off answer
+- adding scripts when prose is enough
+- adding evals before route risk exists
+- adding governance to a personal scaffold with no reuse pressure
+- modifying sibling files because they looked related
+- presenting a recommendation without naming the assumption behind it
@@ -33,6 +33,14 @@ Use this template when a description candidate is ready for human review after a
 - does it avoid stealing sibling routes?
 - does it stay short enough for the target maturity tier?

+## Authoring Discipline
+
+- are unresolved assumptions named or clarified before deepening the package?
+- is the package no larger than the real recurring job requires?
+- do changed files trace directly to the requested improvement?
+- did the author avoid speculative features, decorative folders, and generic configuration?
+- does each new artifact have a verification reason?
+
 ## Decision

 - approve promotion
@@ -32,6 +32,7 @@ Ask only the questions that change the package design.
 - ask boundary questions early
 - ask output questions before architecture questions
 - stop once the skill can be described clearly in one sentence
+- do not enter deep authoring until the recurring job, target output, and exclusion boundary are clear enough to defend

 ## First Message Pattern

@@ -128,6 +129,8 @@ Do not continue into full authoring when the dialogue still leaves these unresol
 - which near-neighbor requests should not trigger
 - what concrete deliverable the skill must return

+If one of these is unresolved, ask the smallest possible follow-up that will unlock the design. Do not compensate by adding extra references, scripts, or governance.
+
 Also treat these as dialogue failures:

 - the first reply feels like a cold worksheet instead of a guided conversation
@@ -6,6 +6,8 @@ This spec defines where information belongs inside a skill package.

 Keep the main skill small enough to route and execute clearly. Move detail out of `SKILL.md` as soon as it stops helping routing or branch selection.

+Do not add structure for imagined future needs. A folder, script, eval, or governance file belongs in the package only when it reduces current ambiguity, execution burden, route risk, or maintenance risk.
+
 ## Context Budget Tiers

 Use the lightest budget that still fits the package.
@@ -60,6 +62,8 @@ Avoid these:
 - adding `evals/` for one-off or disposable skills
 - creating every folder by default even when empty
 - keeping folders that are neither referenced in `SKILL.md` nor declared as factory components
+- adding broad configuration knobs before a real variation exists
+- adding governance or reports to make a scaffold look mature when no reuse pressure exists

 ## Heuristics

@@ -112,3 +116,5 @@ Higher density means the package is staying lean while still proving quality.
 ## Quality Intent

 The best skill is not the one with the most files. The best skill is the smallest package that still makes the recurring job reliable, reusable, and auditable.
+
+See [Authoring Discipline](authoring-discipline.md) for the author and reviewer rules that keep resource growth tied to a real user goal.
@@ -9,9 +9,10 @@ This doctrine defines the default method for turning messy workflow material int
 3. Choose the smallest viable archetype.
 4. Set one clear capability boundary.
 5. Write and test the trigger description before expanding the body.
-6. Add only the gates that match the risk.
-7. Ship the first routeable package, then pick the three highest-value next iteration directions.
-8. Package and govern the skill only as far as real reuse demands.
+6. Apply authoring discipline: name unresolved assumptions, keep scope small, and tie meaningful changes to checks.
+7. Add only the gates that match the risk.
+8. Ship the first routeable package, then pick the three highest-value next iteration directions.
+9. Package and govern the skill only as far as real reuse demands.

 ## Phase 1: Qualification

@@ -33,6 +34,17 @@ Reject skill creation when the request is only:

 See [Non-Skill Decision Tree](non-skill-decision-tree.md).

+## Phase 1.5: Authoring Discipline
+
+Before expanding the package, apply the execution discipline that keeps the work grounded.
+
+- clarify only the assumptions that change the package design
+- do not add speculative features, generic configurability, or decorative structure
+- when editing an existing skill, touch only files that directly serve the requested change
+- connect each meaningful change to a check: route evidence, sample run, resource-boundary check, governance check, or reviewer note
+
+See [Authoring Discipline](authoring-discipline.md).
+
 ## Phase 2: Intent Dialogue

 Before deep authoring, ask only the questions that change the package design.
@@ -121,8 +133,9 @@ The first package is a routeable baseline, not the final answer.
 - add one execution asset before adding many documents
 - surface the three highest-value next moves so authors do not expand in every direction at once
 - prefer the smallest step that increases reliability more than context cost
+- move unverifiable ideas into next-step candidates instead of shipping them as baseline structure

-See [Iteration Philosophy](iteration-philosophy.md).
+See [Iteration Philosophy](iteration-philosophy.md) and [Authoring Discipline](authoring-discipline.md).

 ## Phase 9: Promotion

@@ -709,6 +709,27 @@ def render_html(report: dict) -> str:
        </ul>
      </div>
    </section>
+
+    <section class="grid">
+      <div class="panel">
+        <h2>Authoring discipline</h2>
+        <ul>
+          <li>Name unresolved assumptions before deepening the package.</li>
+          <li>Keep the package no larger than the recurring job requires.</li>
+          <li>Touch only files that directly support the requested change.</li>
+          <li>Tie every meaningful new artifact to a check or reviewer note.</li>
+        </ul>
+      </div>
+      <div class="panel">
+        <h2>Reviewer guardrails</h2>
+        <ul>
+          <li>Block speculative features that are not backed by real workflow variation.</li>
+          <li>Move unverifiable ideas into next-step candidates instead of baseline structure.</li>
+          <li>Reject decorative folders, reports, or governance that do not reduce risk.</li>
+          <li>Ask for one high-leverage clarification when job, output, or exclusion is still fuzzy.</li>
+        </ul>
+      </div>
+    </section>
  </div>
 </body>
 </html>