Concept Design — Modular, Legible Software, Architecture in Practice

Independent modules, clear rules, architecture put into practice

Express the business in a shared language, organize concepts within clear boundaries, keep business rules independent and dependency direction explicit, and stay consistent from design to code.

Define the useful behavior before choosing its implementation.

Adapts ideas from WYSIWID (Meng & Jackson, MIT).

Software structure should directly express behavior observable to users. Concepts define independent functionality; synchronization rules define how concepts work together. It should be possible to locate the corresponding concepts and rules when understanding or changing a behavior.

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:

text

$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.

sh

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. Sources and local conventions.