4-skill 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "4-skill",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Three practical AI agent skills for repository understanding, research, and delivery planning",
   "type": "module",
   "bin": {

package/skills/delivery-plan/SKILL.md

@@ -5,24 +5,39 @@ description: Turn a product or engineering request into a small, verifiable impl
 
 # Delivery Plan
 
-Use this skill when an idea, bug report, or feature request needs to become executable engineering work.
+Use this skill when an idea, bug report, or feature request needs to become executable engineering work, especially when implementation scope or acceptance behavior is still unclear.
 
-## Method
+## Workflow
 
-1. Restate the desired outcome and identify the user or system affected.
-2. Inspect the relevant repository surfaces before proposing files or APIs.
-3. Separate explicit requirements, assumptions, non-goals, and unresolved choices.
-4. Break the work into ordered slices that can each be implemented and checked.
-5. Write `DELIVERY_PLAN.md` unless another output path is requested.
+1. Restate the desired outcome and identify the user, operator, or system affected.
+2. Inspect the relevant repository surfaces, existing patterns, tests, and ownership boundaries before proposing files or APIs.
+3. Separate explicit requirements, assumptions, non-goals, constraints, and unresolved product choices.
+4. Describe the intended behavior, including success, failure, empty, permission, and compatibility cases that matter.
+5. Break the work into ordered vertical slices that can each be implemented and checked.
+6. Name likely files or modules, but verify those paths before presenting them as facts.
+7. Write `DELIVERY_PLAN.md` unless another output path is requested.
 
 ## Include
 
 - Problem statement and goals
-- Assumptions and non-goals
+- Users, workflows, and non-goals
+- Assumptions, constraints, and decisions needed
 - Proposed behavior and technical approach
-- Ordered tasks with likely files or modules
-- Acceptance criteria
-- Focused test strategy
+- Ordered tasks with likely files or modules and a validation step for each
+- Acceptance criteria written as observable behavior
+- Focused unit, integration, and regression test strategy as applicable
 - Risks, rollback considerations, and open questions
 
+## Planning Rules
+
+- Prefer the smallest change that satisfies the stated outcome and fits existing conventions.
+- Keep tasks independently reviewable; avoid combining migration, UI, API, and cleanup work without a dependency reason.
+- Tie each acceptance criterion to a test, inspection, or reproducible manual check.
+- Call out data migrations, rollout flags, backwards compatibility, security, and observability when they apply.
+- Distinguish repository facts from proposed design choices.
+
+## Completion Check
+
+Before finishing, confirm that an implementer can identify what to change, in what order, how to verify it, what is deliberately out of scope, and which decisions still require the requester's answer.
+
 Do not silently decide between materially different product behaviors. Make the smallest useful plan that still gives an implementer a clear validation path.

package/skills/repo-map/SKILL.md

@@ -5,14 +5,16 @@ description: Build an evidence-based map of a software repository for onboarding
 
 # Repository Map
 
-Use this skill when someone needs to understand an unfamiliar repository or locate the right implementation surface.
+Use this skill when someone needs to understand an unfamiliar repository, locate the right implementation surface, or prepare a focused onboarding guide.
 
-## Method
+## Workflow
 
-1. Inspect the top-level tree, manifests, configuration, documentation, entry points, and tests.
-2. Follow one representative execution path from its entry point through the main modules.
-3. Verify commands and claims against files; label anything that could not be confirmed.
-4. Write `REPOSITORY_MAP.md` unless another output path is requested.
+1. Establish the repository root and inspect the top-level tree before opening broad file sets.
+2. Read manifests, configuration, documentation, entry points, and tests that control the requested area.
+3. Trace one representative execution path from its entry point through the modules that compute or mutate the behavior.
+4. Identify the cheapest command that can validate the map's important claims, and run it when tools permit.
+5. Verify every command, dependency, path, and behavior claim against the repository. Mark unavailable or unverified information explicitly.
+6. Write `REPOSITORY_MAP.md` unless another output path is requested.
 
 ## Include
 
@@ -21,6 +23,19 @@ Use this skill when someone needs to understand an unfamiliar repository or loca
 - Important directories and files
 - Install, development, test, and build commands
 - Configuration, external services, and environment variables
+- Extension points and likely ownership boundaries
 - Risks, unknowns, and useful next steps
 
+## Evidence Rules
+
+- Prefer source code, tests, package manifests, and configuration over assumptions or naming conventions.
+- Link claims to paths and symbols where the output format supports links.
+- Distinguish observed behavior, inferred behavior, and recommended changes.
+- Do not describe generated, ignored, or unavailable files as committed source files.
+- If the repository is too large for a full inspection, state the scope and explain how the sampled paths were selected.
+
+## Completion Check
+
+Before finishing, confirm that the map answers: where does execution start, where is the main behavior decided, how is it tested, how is it run or shipped, and what remains uncertain?
+
 Keep the result concise and operational. Never invent behavior, dependencies, or files.

package/skills/source-scout/SKILL.md

@@ -7,21 +7,37 @@ description: Investigate a technical question using authoritative sources and pr
 
 Use this skill to compare tools, investigate a technical claim, or prepare a recommendation that depends on external evidence.
 
-## Method
+## Workflow
 
-1. Define the decision, constraints, and questions that must be answered.
-2. Start with user-provided links, official documentation, specifications, and primary sources.
-3. Record the source for every material claim and distinguish facts from interpretation.
-4. Prefer current sources; state the access date when available.
-5. Write `DECISION_BRIEF.md` unless another output path is requested.
+1. Define the decision, constraints, audience, and questions that must be answered.
+2. Turn each question into a claim or comparison criterion that can be checked independently.
+3. Start with user-provided links, official documentation, specifications, release notes, and primary sources.
+4. For each material claim, record the source, publication or update date when available, and the relevant evidence.
+5. Separate verified facts, source-reported recommendations, assumptions, and your own interpretation.
+6. Check important claims against more than one authoritative source when sources disagree or the decision is high risk.
+7. State the research cutoff date and write `DECISION_BRIEF.md` unless another output path is requested.
 
 ## Include
 
 - Decision summary
-- Findings grouped by question
+- Scope, constraints, and definitions
+- Findings grouped by question or comparison criterion
 - Comparison and trade-offs
 - Recommendation tied to the stated constraints
 - Sources with inline links
+- Confidence or evidence-quality notes for consequential findings
 - Unresolved questions and verification steps
 
+## Evidence Rules
+
+- Use primary sources for product behavior, compatibility, security, licensing, pricing, and limits whenever possible.
+- Do not treat search snippets, marketing claims, or a single anecdote as proof of behavior.
+- Quote or paraphrase only what the cited source supports; do not let a citation imply support for nearby uncited claims.
+- Say when a source was unavailable, stale, contradictory, or not independently verified.
+- Do not fabricate citations, access dates, benchmarks, or conclusions.
+
+## Completion Check
+
+Before finishing, confirm that every recommendation maps to a stated constraint, every important factual claim has a source, trade-offs are explicit, and the reader knows what to verify before committing.
+
 Do not imply that a source was consulted when it was not. Do not turn a weak source into certainty through confident wording.