Write Engineering Proposal

Write Engineering Proposal

Turn settled discussion into a decision-ready engineering document grounded in the current codebase. Adapt the document to the change; do not force every proposal through the same headings.

Read references/proposal-boundaries.md before starting.

Workflow

1. Recover the decision context

Extract from the conversation:

• the problem and desired outcome;
• decisions already accepted;
• rejected approaches and reasons;
• constraints, invariants, and non-goals;
• unresolved questions.

Do not reopen settled decisions without new repository evidence. Ask only when a missing decision blocks a coherent proposal; otherwise record it as an open question with a recommended default.

2. Ground the proposal in the repository

Read repository instructions first, then locate product, architecture, engineering, security, testing, release, and planning sources relevant to the change. Inspect actual entry points, composition, contracts, state ownership, persistence, and tests.

Search for existing proposals, ADRs, and execution-plan conventions. Reuse repository terminology and destination conventions. If no document convention exists, ask whether the user wants a file or an in-chat draft before creating a new documentation hierarchy.

3. Classify engineering concerns

Select every material lens and read only its reference:

| Concern | Trigger | Reference | | --- | --- | --- | | Desktop/platform | Native APIs, tray/menu-bar, Tauri/Electron, OS lifecycle, packaging | references/desktop-platform.md | | Mobile/platform | Android/iOS lifecycle, permissions, background work, device capabilities | references/mobile-platform.md | | API/distributed systems | HTTP/RPC, remote services, queues, retries, contracts | references/api-distributed-systems.md | | Data/persistence/sync | Databases, migrations, caches, offline data, synchronization | references/data-persistence-sync.md | | Security/privacy | Identity, auth, secrets, sensitive data, trust boundaries | references/security-privacy.md | | UI/product state | User workflows, navigation, state ownership, accessibility | references/ui-product-state.md | | Background processing | Schedulers, workers, long-running tasks, concurrency | references/background-processing.md | | Local ingestion | Files, local databases, external-tool artifacts, incremental collection | references/local-ingestion.md | | Delivery/operations | CI, deployment, packaging, updates, rollback, runtime proof | references/delivery-operations.md |

Use multiple lenses when needed. A desktop authentication proposal may require desktop, API, data, security, UI, background, and delivery lenses.

4. Design from evidence

For each selected lens:

1. answer its material questions from code and repository documentation;
2. identify ownership and boundaries using real symbols and paths;
3. distinguish current behavior from proposed behavior;
4. record alternatives only when they were plausible or discussed;
5. state uncertainty where runtime or external evidence is missing.

Prefer concrete flows, state transitions, and invariants over labels such as "clean," "scalable," or "enterprise."

5. Decide whether a diagram is needed

Read references/diagram-guidance.md when the proposal crosses multiple runtime or trust boundaries, depends on non-obvious event ordering, contains meaningful lifecycle states, or changes deployment topology.

Use a diagram only when it makes ownership, order, state, or data movement clearer than prose. Diagrams are part of the explanation, not decoration.

6. Write the smallest complete proposal

Most proposals need:

• status and scope;
• summary or recommendation;
• context and problem;
• goals and non-goals;
• constraints or invariants;
• proposed design, ownership, and runtime/data flow;
• material risks and tradeoffs;
• acceptance criteria;
• open questions that genuinely remain.

Add lens-specific sections only when they contain useful decisions. A narrow refactor may be a few pages. Split research inventories, detailed protocols, rollout runbooks, or implementation checklists into supporting documents when they overwhelm the decision.

High-level phases are allowed to show sequencing. Exact file-by-file tasks, command logs, progress tracking, and runtime artifacts belong in an execution plan or evidence document.

7. Self-review before delivery

Check silently:

• Every important claim is grounded in discussion or repository evidence.
• Current and proposed behavior are not mixed together.
• Ownership is explicit at important boundaries.
• Relevant failure, compatibility, privacy, and rollout concerns are covered.
• Every diagram clarifies a real decision and agrees with the written invariants.
• No section exists only because a template listed it.
• The proposal does not pretend unresolved decisions are settled.
• The document does not authorize implementation unless the repository explicitly uses proposals that way.

Writing Rules

• Match repository naming, heading style, location, and status conventions.
• Use plain language and short paragraphs.
• Link to source-of-truth documents instead of duplicating them.
• Use tables for matrices and compact comparisons. Follow references/diagram-guidance.md when a diagram is justified.
• Include code or schemas only when they define a contract or remove ambiguity.
• Preserve unrelated working-tree changes.
• Do not implement, create execution plans, add ADRs, commit, or push unless separately requested.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fikrilal
• Source: fikrilal/engineering-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.