proofline
TR

system-design

Purpose

Designs the smallest valid architecture for a task, or reverse-engineers docs/design/ARCHITECTURE.md from an existing codebase.

Source Skill purpose

When to use it

Use system-design for complex work that crosses component boundaries or needs an architecture decision grounded in the repository. It chooses only the context, container and component detail the task needs. Each proposed component maps to a verified path and a responsibility, while boundaries name their contracts. Compatibility, migration and alternatives are recorded; an ADR appears only for a real decision. Reverse mode can recover an architecture document from existing code instead of inventing future structure.

The survey checks entry points and dependency direction before a boundary is proposed. Compatibility and migration are explicit even when their result is none, with the reason recorded. A requirement-level choice that the task has not settled is returned for input instead of resolved by the designer.

Source Skill purpose

How it works

Steps of the skill, in source orderEach numbered step follows the skill definition and links to its source.1. Set scopeFlow2. Survey the codeFlow3. Choose levelsFlow4. Map componentsFlow5. Assess compatibilityFlow6. Record decisionsFlow7. Write architectureFlow8. Validate pathsFlow9. Report designFlow
Steps of the skill, in source order

Source Flow

  1. Set scope Read the assignment and identify criteria that require structure or a repository survey.

    Source Flow

  2. Survey the code Inspect entry points, modules, dependency direction, existing architecture and ADRs with paths.

    Source Flow

  3. Choose levels Use only the context, container or component levels needed by the change.

    Source Flow

  4. Map components Record each component's verified path, responsibility, change and boundary contract.

    Source Flow

  5. Assess compatibility Explain effects on callers, migration steps and architectural trade-offs.

    Source Flow

  6. Record decisions Write an ADR only when evidence supports genuine alternatives; ask about missing requirements.

    Source Flow

  7. Write architecture Produce machine-readable architecture and the human document from verified repository facts.

    Source Flow

  8. Validate paths Run architecture validation and correct invalid paths or incomplete decisions.

    Source Flow

  9. Report design Summarize levels, components, boundaries, ADRs, compatibility and remaining risks.

    Source Flow

Key rules

  • Design the smallest architecture that satisfies the task's acceptance criteria.

    Source Hard rules

  • Tie every component to an existing repository path.

    Source Hard rules

  • Read current entry points and dependency conventions before proposing structure.

    Source Hard rules

  • Write ADRs only for decisions with real alternatives and evidence.

    Source Hard rules

  • Name the contract across every component boundary.

    Source Hard rules

Output and gate

Output

  • Produce architecture data, a readable architecture document, warranted ADRs and a ledger.

    Source Output

Gate

  • Validation must succeed; missing component paths or unsupported ADR choices prevent completion.

    Source Gate rule

Source

Source Skill definition

← All skills