concept-design

Use only when explicitly invoked for software design, specifications, implementation, review, refactoring, or explanation with Daniel Jackson's concepts and synchronizations. Put functionality in inde

SKILL.md

GitHub

Concept design

Define independent functionality with concepts and coordinate them with synchronization rules. Specify the behavior users need before choosing an implementation. When understanding or changing a behavior, locate its concepts and rules.

This skill adapts Meng and Jackson's WYSIWID method.

Start from the need

  • Name the beneficiary and the observable result they need.
  • A concept provides independent behavior for one purpose.
  • Its state and actions define allowed behavior.
  • Its operational principle (OP) explains a representative history that fulfills the purpose.
  • An OP does not specify every behavior or guarantee progress.
  • Each concept instance owns its state.
  • Concepts MUST NOT invoke one another or read one another's state.
  • External identities carry no assumed fields from another concept.
  • Put application coordination in external synchronization rules.
  • Composition MAY restrict behavior but MUST preserve each concept's contract.

Test the argument

  • State the claim, its evidence, and the assumptions it needs.
  • Find a scenario that would make the claim false.
  • Compare alternatives, including no change.
  • If fixes fail under the same assumption, re-examine that assumption.
  • Check that the contract supports the OP.
  • Check that the OP serves the purpose.
  • Check application scenarios separately from concept correctness.
  • State required timing, failure, and consistency assumptions.
  • A missing decision stays open; an absent test stays unverified.

Make each decision once

  • Distinguish confirmed, proposed, inferred, and open statements.
  • A proposal or inference MUST NOT become a confirmed requirement by transcription.
  • Keep one authoritative definition of each model element.
  • Reuse confirmed decisions until requirements or evidence justify revisiting them.
  • Before adding a mechanism, check whether removing a rule or responsibility would preserve the required behavior.
  • Preserve behavior during refactoring; identify intentional redesign separately.

Choose the work

These are prompt selectors, not installed shell commands:

$concept-design [design|settle|prd|build|review|guard|refine|explain] [scope and request]
$concept-design guard [audit|concept|drift|pipeline|sync|map] [scope]

Infer the mode from the request when omitted. If intent is unclear, inspect read-only before asking about a blocking choice. Read only the selected workflow. Continue already authorized work when it crosses modes.

Mode Read when needed Result
design Design Concepts, composition, and decisions
settle Settle Discussion consolidated with decision status
prd Specifications Confirmed model and acceptance recorded
build Implementation Scoped implementation, structural review, or refactoring
review Review Read-only findings with evidence
guard Maintenance Coverage, backfill, drift, pipeline, or a concept and synchronization diagram
refine Refinement A proposal or authorized design correction
explain Explanation A source-backed view of behavior

Review, audit, drift, and plan-only requests MUST remain read-only. Other modes write only within the requested scope. A backfill MUST separate observed code, inferred purpose, defects, and confirmed requirements. MUST NOT change a specification to conceal a code defect.

Specifications and checks

Diagrams MUST use Mermaid code blocks in Markdown. Use the CONCEPT/SYNCS format when writing or comparing specifications.

python3 <skill-directory>/scripts/concept_lint.py <CONCEPT.md-or-SYNCS.md> [more-files] --json

A syntax result does not establish purpose fulfillment, contract conformance, or runtime correctness. References.