mino-driven-design-skills

# mino-driven-design-skills > Skill by [ara.so](https://ara.so) — Design Skills collection. This skill enables AI agents to apply systematic design principles extracted from Mino-san's public materials. It guides you through problem framing, domain modeling, contract-based design, interface/implementation separation, architecture quality strategy, and reproducible development workflows—before, during, and after implementation. **Core philosophy**: Don't confuse problems with solutions. Track requirements from natural language through models, contracts, public operations, and tests. Use evidence (code, contract tests, quality scenarios, independent validation) rather than explanations. Let humans own final value judgments, public contracts, irreversible decisions, and release approval. ## What This Skill Provides The suite contains **independent skills** for different phases: | Skill | When to Use | Primary Artifacts | |-------|-------------|-------------------| | `mino-core` | Common decision framework (usually invoked by other skills) | Problem Frame, Context Packet, Requirement Catalog | | `mino-problem-framing` | Separate observations, assumptions, problems, objectives, success criteria before designing | Problem Framing Package | | `mino-domain-model-completeness` | Audit for missing concepts, states, constraints, failures, authorities in a use case | Completeness Package | | `mino-design-by-contract` | Convert natural language requirements into preconditions, postconditions, invariants, failure guarantees, contract tests | Contract Package | | `mino-interface-implementation-separation` | Identify caller-side branching and technical leakage; design boundaries around intent and contract | Boundary Package | | `mino-architecture-quality-strategy` | Design system-wide structure, data ownership, quality trade-offs, migration, recovery | Architecture Strategy Package | | `mino-reproducible-development` | Integrate multiple design artifacts with implementation, review, and independent verification for medium-to-large changes | Implementation Spec, Verified Change, Review Result, or Reproduction Report | ## Installation Clone the repository and reference the `.agents/skills/` directory from your AI agent configuration: ```bash git clone https://github.com/my-take-dev/inspired-mino-design-skills.git cd inspired-mino-design-skills ``` ### Adding to Your Project Create or update `.agents/AGENTS.md` in your project: ```markdown # Skill Composition When a request matches multiple Skills: - Use the Skill that best matches the primary outcome as the basic workflow. - Add only relevant language-, framework-, or tool-specific Skills to supplement that workflow. - Let the basic Skill control scope, changes, validation, and the final response; specialized Skills provide their domain-specific guidance. - Preserve every applicable Skill's exclusions, hard gates, and safety constraints. - Follow the user's explicitly named Skills and do not add unrelated Skills. ## Skills - [mino-driven-design-skills](./inspired-mino-design-skills/.agents/skills/) ``` ## Skill Selection by Development Phase | Phase | Skill | Developer Timing | |-------|-------|------------------| | Design | `mino-problem-framing` | Before implementation: organize the problem, objectives, assumptions, success criteria | | Design | `mino-domain-model-completeness` | Check for missing business concepts, states, constraints, behaviors | | Design | `mino-design-by-contract` | Convert requirements into testable conditions for normal and exceptional cases | | Design | `mino-interface-implementation-separation` | Separate caller-facing operations from internal implementation choices | | Architecture Design | `mino-architecture-quality-strategy` | Design system structure, data management, migration, recovery | | Design + Implementation + Review | `mino-reproducible-development` | Medium-to-large changes requiring multiple design viewpoints through implementation and verification | | Usually Not Direct | `mino-core` | Invoked by other skills; developers rarely call directly | **Guidance**: For new features or major changes, start with `mino-problem-framing` to establish design premises. Then choose one design skill. Use `mino-reproducible-development` only when integrating multiple viewpoints through implementation and review. For small, mechanical changes (rename) with approved baseline problem/contract/data-meaning, this suite is unnecessary. ## Usage Patterns ### Pattern 1: Problem Framing Before Design **Scenario**: You have a feature request but requirements are vague or solution-led. ```bash # Request to AI agent: "Help me frame this problem before designing: users complain the report is slow" ``` **Expected artifacts**: - `Problem Framing Package` containing: - **Observations**: Current behavior, measurements, constraints - **Assumptions**: What we believe but haven't validated - **Problem Statement**: Core issue to solve - **Objectives**: Desired outcomes, not implementation - **Success Criteria**: Measurable, testable conditions **Example output structure** (Markdown): ```markdown # Problem Framing Package ## Observations - Report generation takes 45s for 10,000 rows (measured 2026-07-14) - Database query plan shows full table scan - Users request report 200 times/day during business hours ## Assumptions - Current database schema cannot be changed without migration plan - Users expect <5s response for report generation - Report content must remain accurate (no sampling trade-off) ## Problem Statement Report generation exceeds user patience threshold due to query inefficiency. ## Objectives - Reduce report generation time to <5s for typical dataset - Maintain data accuracy and completeness - Minimize infrastructure cost increase ## Success Criteria - 95th percentile response time <5s for 10,000-row dataset - Zero data discrepancies vs. current report - Infrastructure cost increase <20% ``` ### Pattern 2: Domain Model Completeness Audit **Scenario**: You have a use case but want to find missing concepts, states, constraints. ```bash # Request to AI agent: "Verify my domain model is complete for order fulfillment use case" ``` **Expected artifacts**: - `Completeness Package` with: - **Concept Coverage**: Entities, value objects, aggregates - **State Coverage**: Lifecycles, transitions, terminal states - **Constraint Coverage**: Invariants, business rules - **Failure Coverage**: Error conditions, compensations - **Authority Coverage**: Who can perform which operations **Example output** (Markdown checklist): ```markdown # Completeness Package: Order Fulfillment ## Concept Coverage - [x] Order (aggregate root) - [x] OrderLine (entity, child of Order) - [x] Customer (reference) - [x] Product (reference) - [x] InventoryReservation (entity) - [ ] **GAP**: ShippingAddress (value object) — currently string, needs validation - [ ] **GAP**: PaymentMethod (value object) — no expiration tracking ## State Coverage - [x] Order states: Draft, Submitted, Confirmed, Shipped, Delivered, Cancelled - [ ] **GAP**: No "PartiallyShipped" state for multi-line orders - [ ] **GAP**: No terminal failure state (what if payment fails after shipment?) ## Constraint Coverage - [x] Order total = sum(OrderLine.price * OrderLine.quantity) - [x] Cannot ship order with insufficient inventory - [ ] **GAP**: No constraint for maximum order size - [ ] **GAP**: No constraint preventing duplicate submissions ## Failure Coverage - [x] Insufficient inventory → reject order - [x] Payment declined → cancel order - [ ] **GAP**: No compensation for shipped-but-unpaid orders - [ ] **GAP**: No handling for partial inventory availability ## Authority Coverage - [x] Customer can submit order - [x] Warehouse can mark order shipped - [ ] **GAP**: Who can cancel order after shipment? - [ ] **GAP**: Can customer modify order after confirmation? ``` ### Pattern 3: Design by Contract **Scenario**: Convert natural language requirements into preconditions, postconditions, invariants, and contract tests. ```bash # Request to AI agent: "Convert these requirements into contracts with test oracles: order submission must validate inventory and reserve stock" ``` **Expected artifacts**: - `Contract Package` with: - Preconditions (caller responsibilities) - Postconditions (operation guarantees) - Invariants (always-true conditions) - Failure guarantees (what's preserved on error) - Contract test oracles **Example output** (TypeScript with contract tests): ```typescript // contract/order-submission.contract.ts /** * Contract: submitOrder * * Preconditions: * - order.lines.length > 0 * - order.customer exists and is active * - all order.lines[].product exist * * Postconditions (success): * - order.state === OrderState.Submitted * - for each line: inventory.reserved >= line.quantity * - database transaction committed * * Postconditions (failure): * - order.state unchanged * - no inventory reserved * - database transaction rolled back * * Invariants: * - inventory.available + inventory.reserved === inventory.total (always) * - order.totalPrice === sum(line.price * line.quantity) (always) */ describe('Contract: submitOrder', () => { test('PRECONDITION VIOLATION: empty order lines → reject immediately', async () => { const order = { lines: [], customer: validCustomer }; await expect(submitOrder(order)).rejects.toThrow(PreconditionError); // ORACLE: no database write, no inventory touch expect(await db.orders.count()).toBe(0); expect(await inventory.getReservations()).toHaveLength(0); }); test('POSTCONDITION SUCCESS: sufficient inventory → order submitted + inventory reserved', async () => { const order = { lines: [{ product: 'P1', quantity: 5, price: 100 }], customer: validCustomer, }; await inventory.setAvailable('P1', 10); const result = await submitOrder(order); // Postconditions expect(result.state).toBe(OrderState.Submitted); expect(await inventory.getReserved('P1')).toBe(5); expect(await db.orders.findById(result.id)).toBeDefined(); }); test('POSTCONDITION FAILURE: insufficient inventory → order unchanged + no reservation', async () => { const order = { lines: [{ product: 'P1', quantity: 15, price: 100 }], customer: validCustomer, }; await inventory.setAvailable('P1', 10); await expect(submitOrder(order)).rejects.toThrow(InsufficientInventoryError); // Failure guarantee: no side effects expect(await db.orders.count()).toBe(0); expect(await inventory.getReserved('P1')).toBe(0); }); test('INVARIANT: available + reserved === total (always maintained)', async () => { const before = await inventory.get('P1'); expect(before.available + before.reserved).toBe(before.total); const order = { lines: [{ product: 'P1', quantity: 5, price: 100 }], customer: validCustomer, }; await submitOrder(order); const after = await inventory.get('P1'); expect(after.available + after.reserved).toBe(after.total); }); }); ``` ### Pattern 4: Interface/Implementation Separation **Scenario**: Identify caller-side branching and technical leakage; design boundaries around intent. ```bash # Request to AI agent: "Separate interface from implementation properly for notification sending" ``` **Expected artifacts**: - `Boundary Package` with: - Caller intent (what, not how) - Public contract - Hidden implementation choices - Eliminated caller-side branching **Example output** (Go): ```go // BEFORE: caller must know implementation details func NotifyUser(userID string, message string, useEmail bool, useSMS bool) error { if useEmail { return emailService.Send(userID, message) // caller decides transport } if useSMS { return smsService.Send(userID, message) } return errors.New("no notification method specified") } // PROBLEM: caller must know // - which transports exist // - how to choose between them // - transport-specific error handling // AFTER: caller expresses intent; implementation chooses transport type NotificationIntent struct { UserID string Message string Urgency UrgencyLevel // High, Normal, Low } type NotificationService interface { // Contract: // - Precondition: intent.UserID exists, intent.Message non-empty // - Postcondition: at least one transport attempted; user preferences respected // - Failure guarantee: logs delivery attempts; no partial state Notify(ctx context.Context, intent NotificationIntent) error } type notificationService struct { userPrefs UserPreferenceRepository transports []Transport // email, SMS, push, etc. } func (s *notificationService) Notify(ctx context.Context, intent NotificationIntent) error { // Implementation chooses transport based on: // - user preferences (hidden from caller) // - urgency level (caller specifies WHAT urgency means, not HOW to handle it) // - transport availability (hidden from caller) prefs, err := s.userPrefs.Get(ctx, intent.UserID) if err != nil { return fmt.Errorf("load user preferences: %w", err) } candidates := s.selectTransports(intent.Urgency, prefs) for _, transport := range candidates { err := transport.Send(ctx, intent.UserID, intent.Message) if err == nil { return nil // success on first available } log.Warn("transport %s failed: %v", transport.Name(), err) } return errors.New("all transports failed") } // Caller code (simplified): func HandleOrderShipped(orderID string) error { // Caller only expresses INTENT, not implementation return notificationService.Notify(ctx, NotificationIntent{ UserID: order.CustomerID, Message: fmt.Sprintf("Order %s shipped", orderID), Urgency: UrgencyNormal, }) } ``` **Key improvements**: - Caller no longer branches on transport type - Transport selection logic hidden in implementation - User preferences hidden from caller - New transports can be added without changing caller ### Pattern 5: Architecture Quality Strategy **Scenario**: System-wide design with quality trade-offs, data ownership, migration, recovery. ```bash # Request to AI agent: "Design architecture quality strategy for multi-tenant SaaS with data sovereignty requirements" ``` **Expected artifacts**: - `Architecture Strategy Package` with: - Quality portfolio (optimized vs. constrained vs. deliberately not optimized) - Module structure and data ownership - Cross-cutting concerns (observability, security, resilience) - Migration and recovery strategy - Trade-off decisions with rationale **Example output** (Markdown): ```markdown # Architecture Strategy Package: Multi-Tenant SaaS with Data Sovereignty ## Quality Portfolio | Quality Attribute | Strategy | Rationale |