ss-learn

Learn from project design decisions

ss-learn turns a specific human-approved correction into a generalized candidate rule. It does not train a model, scrape a repository, or upload telemetry. The CLI is local-only. An optional plugin MCP bridge can expose one exact package to its connected client/model only after a separate one-time human grant.

Read references/privacy-contract.md before using this skill.

When not to use

• The user did not explicitly ask to capture or share a lesson.
• The change was accepted only by the agent, not a person.
• The lesson cannot be expressed without client/product identity, source code, a screenshot, proprietary tokens, or user content.
• A score or visual pass was not actually measured. Record it as null or not-run; never infer.
• The observation belongs only to one project's taste. Keep it in STYLESEED.md instead.

1. Initialize local learning

After explicit user approval:

node <installed-ss-learn>/scripts/learning.mjs init --project-root .

This creates .styleseed/learning/config.json with sharing disabled and all raw-material collection disabled. It performs no network request.

2. Draft a candidate

Use references/candidate.schema.json. Generalize the lesson:

• problem: what design failure was observed;
• intervention: what bounded change the person accepted;
• rationale: why it improved the product job;
• appliesWhen: conditions where the judgment should transfer;
• avoidWhen: counterexamples and failure boundaries;
• evidence: only measured scores, verification status, and optional SHA-256 artifact hashes.

Do not include project names, URLs, paths, emails, source snippets, prompts, screenshots, colors, font names, or component names. Then capture it:

node <installed-ss-learn>/scripts/learning.mjs capture \
  --project-root . \
  --input /path/to/candidate.json

The CLI validates maintained context IDs, exact fields, privacy patterns, and evidence honesty. It writes an immutable draft ID under .styleseed/learning/candidates/.

3. Human review

Show the full candidate to the user. Only after their explicit accept/reject decision run:

node <installed-ss-learn>/scripts/learning.mjs review \
  --project-root . \
  --id <candidate-id> \
  --decision accepted \
  --reviewer <local-alias> \
  --reason "<why this generalizes>" \
  --attestation APPROVE_LOCAL_REVIEW

Use --decision rejected for a counterexample. Never accept on the user's behalf. A candidate is content-addressed and receives one final local decision; revise the source lesson and capture a new candidate instead of rewriting an accepted or rejected record.

4. Prepare an opt-in share package

Only an accepted candidate can be packaged. Show the sanitized payload and ask separately whether the user approves export for team-registry or community-candidate:

node <installed-ss-learn>/scripts/learning.mjs prepare-share \
  --project-root . \
  --id <candidate-id> \
  --purpose team-registry \
  --attestation APPROVE_LOCAL_EXPORT

This writes .styleseed/learning/share/<id>.<purpose>.json. It strips reviewer identity and local paths, binds the payload to the engine revision, and records a content hash. It does not send the file anywhere.

5. Grant one MCP read

Only when the user separately approves exposing the prepared package to the connected MCP client and its model, run:

node <installed-ss-learn>/scripts/learning.mjs grant-mcp-read \
  --project-root . \
  --package .styleseed/learning/share/<package.json> \
  --attestation APPROVE_MCP_READ

The grant is bound to the package hash and accepted local review. The MCP bridge consumes it before returning the package, so retries fail closed. This is client/model exposure even though the MCP server itself performs no network request. Never describe it as remaining local after consumption.

6. Promotion boundary

A share package is evidence, not a StyleSeed rule. Central or team promotion requires multiple independent projects, counterexamples, accessibility and grammar regression checks, benchmark evidence, and named maintainer approval. Never edit core rules automatically from local learning.

Completion report

Report separately:

• local candidate: captured | not captured;
• human review: accepted | rejected | pending;
• visual evidence: verified | failed | not run;
• share package: prepared locally | not prepared;
• MCP grant: absent | available once | consumed;
• client/model exposure: not performed | performed after one-time approval;
• external registry or community transmission: not performed by the CLI or MCP bridge.