feat(skills): restructure adapt skill to Gherkin-style scenarios

.agents/skills/adapt/SKILL.md

@@ -8,7 +8,7 @@ tags:
   - process
 metadata:
   author: Oleg Shulyakov
-  version: "1.2.0"
+  version: "1.3.0"
   source: github.com/olegshulyakov/agent.md
   catalog: utility
   category: productivity
@@ -20,77 +20,91 @@ metadata:
 
 # adapt
 
-Diagnose when skills, rules, workflows, docs, evals, or memory conventions are mismatched to current conditions — from failures, friction, feedback, outdated assumptions, or changed constraints — then name the smallest change needed and route to the skill or workflow that should update it.
+Diagnose mismatches in skills, rules, workflows, docs, evals, or memory — then name the smallest change and apply it by routing to the right skill.
 
 ---
 
-## Workflow
-
-1. **Classify the signal.** Identify which type of mismatch was presented:
-   - *Failure* — an action produced a wrong or broken result
-   - *Friction* — a step is consistently slow, ambiguous, or skipped
-   - *Feedback* — the user explicitly named something that didn't work
-   - *Outdated assumption* — a prior decision no longer holds given current context
-   - *Changed constraint* — external requirements shifted (scope, platform, team, policy)
-
-2. **Test durability.** Skip adaptation if all three are true:
-   - The signal occurred exactly once
-   - No structural cause is identifiable
-   - The user hasn't signaled recurrence ("this keeps happening", "again", "always")
-
-   Otherwise, proceed.
-
-3. **Identify the target artifact.** Match signal type to likely target:
-
-   | Signal | Likely target |
-   | --- | --- |
-   | Failure | skill, eval, test |
-   | Friction | rule, workflow, process |
-   | Feedback | skill, doc, memory |
-   | Outdated assumption | memory, doc, spec |
-   | Changed constraint | rule, PRD, skill |
-
-4. **Prefer the source of truth.** If the artifact inherits from a template, convention, or governing doc, route the change there — not only to the downstream artifact.
-
-5. **Name the smallest change.** One behavioral delta. Not a rewrite.
-
-6. **Route it.** Name the follow-up skill or owner. Do not apply the update unless separately asked.
-
-7. **Define verification.** State what must be true after the adaptation succeeds.
-
----
-
-## Output
-
-- **Signal:** What happened or changed, and which type it is.
-- **Interpretation:** Why it indicates a mismatch, not a one-off.
-- **Target:** The artifact or behavior that should change.
-- **Change:** The smallest useful adaptation — one behavioral delta.
-- **Route:** The follow-up skill or workflow that should apply the update.
-- **Verification:** What must be true after the change succeeds.
-
-### Example
-
-**Signal:** The `create-skill` output omits a Verification section on 3 consecutive runs. *(Friction)*
-**Interpretation:** A recurring omission across runs points to a missing template step, not operator error.
-**Target:** `create-skill` SKILL.md — the output template is missing a required `## Verification` heading.
-**Change:** Add a `## Verification` heading with a placeholder to the skill output template.
-**Route:** `skill-creator` to apply the update.
-**Verification:** The next 3 `create-skill` runs each include a non-empty Verification section without prompting.
-
----
-
-## Boundaries
-
-- **Diagnose, don't rewrite.** Produce a diagnosis and routing recommendation only. Apply the update only when separately asked.
-- **Don't self-target by invocation.** Invoking `adapt` does not make `adapt` the target. Only route changes to `adapt` when the adaptation workflow itself failed.
-- **Keep uncertainty visible.** If the target artifact or routing is unclear, name the candidates and the evidence needed to choose.
-
----
-
-## Verification
-
-- [ ] The signal maps to a concrete observed event, not a vague quality concern
-- [ ] The change would apply to future occurrences, not only this exact incident
-- [ ] No smaller artifact change would address the same signal
-- [ ] A follow-up skill or owner is named for the actual update
+Feature: Diagnose and act on a mismatch signal
+
+  Background:
+    Given the user has presented a signal of mismatch
+    And the signal is one of: failure, friction, feedback, outdated assumption, or changed constraint
+
+## Guard: skip one-offs
+
+  Scenario: Signal is a one-off with no structural cause
+    Given the signal occurred exactly once
+    And no structural cause is identifiable
+    And the user has not signaled recurrence ("this keeps happening", "again", "always")
+    Then explain why no change is warranted
+    And stop
+
+## Classify signal and identify target
+
+  Scenario Outline: Classify signal and map to target artifact
+    Given the signal is a `<type>`
+    Then identify the likely target as `<target>`
+    And proceed to scoping the change
+
+    Examples:
+      | type                 | target                  |
+      | failure              | skill, eval, or test    |
+      | friction             | rule, workflow          |
+      | explicit feedback    | skill, doc, or memory   |
+      | outdated assumption  | memory, doc, or spec    |
+      | changed constraint   | rule, PRD, or skill     |
+
+## Scope the change
+
+  Scenario: Target inherits from a governing doc
+    Given the artifact is downstream of a template, convention, or spec
+    Then route the change to the governing doc first
+    And not only to the downstream artifact
+
+  Scenario: Name the smallest change
+    Given a target artifact is identified
+    Then name exactly one behavioral delta
+    And do not propose a full rewrite
+
+## Act: apply the change
+
+  Scenario: Target is a skill
+    Given the target artifact is a SKILL.md file
+    Then invoke skill-creator to apply the update
+    And preserve the original skill name and frontmatter fields
+    And copy the skill to a writable location before editing if the source is read-only
+
+  Scenario: Target is a rule
+    Given the target artifact is a rule file (.agents/rules/, CLAUDE.md, AGENTS.md, etc.)
+    Then invoke creator-rule to write or update the rule
+    And check for conflicts with existing rules before writing
+    And scope the rule narrowly — one concern per file
+
+  Scenario: Target is a doc or spec
+    Given the target artifact is documentation or a specification
+    Then draft the minimal diff — only the section that changed
+    And present it to the user for confirmation before writing
+
+  Scenario: Target is memory or context
+    Given the target artifact is a memory or convention held in context
+    Then state the updated convention explicitly
+    And ask the user to confirm before treating it as active
+
+  Scenario: Target artifact or routing is unclear
+    Then list the candidate artifacts with supporting evidence for each
+    And ask one question to resolve the ambiguity
+    And do not act until resolved
+
+## Verify
+
+  Scenario: Confirm the action is complete
+    Then state what was changed and where
+    And state what must be true for the change to be considered successful
+    And confirm the signal maps to a concrete event, not a vague concern
+    And confirm the change addresses future occurrences, not only this incident
+    And confirm no smaller change would have addressed the same signal
+
+## Boundary
+
+  Scenario: adapt itself is invoked but its own workflow did not fail
+    Then do not route changes back to adapt