gaziwang/embedded-project-planner

Embedded Project Planner

Create evidence-based embedded project plans that connect product requirements to hardware constraints, firmware components, verification, and production readiness. Prefer concrete interfaces, budgets, failure behavior, and acceptance criteria over generic task lists.

Select the Planning Mode

• Use greenfield mode for a new device or major redesign. Build all sections and expose missing hardware decisions early.
• Use existing-project mode when source code, schematics, configuration files, logs, or test artifacts exist. Inspect them before planning and distinguish observed facts from proposed changes.
• Use focused mode for one subsystem or decision. Analyze the affected dimensions deeply, then summarize impacts on the other dimensions instead of pretending they are unrelated.
• Use recovery mode for a delayed or failing project. Establish current evidence, identify the critical path and unstable interfaces, then produce a re-baselined plan with containment work.

Establish Evidence

Inspect the materials available in the workspace before drawing conclusions. Prioritize product requirements, schematics and BOM, MCU and peripheral datasheets, pin maps, clock trees, memory maps, CubeMX or vendor configuration, linker maps, source layout, protocol specifications, logs, and existing tests.

Classify every important statement as one of:

• Fact: supported by supplied material or inspected artifacts. Cite the source.
• Assumption: necessary to proceed but not yet confirmed. State impact and validation date or owner.
• Decision: selected approach with alternatives and rationale.
• Open question: information whose answer may materially change scope, hardware, architecture, safety, schedule, or cost.

Ask only questions that block a safe or useful plan. For non-blocking gaps, use explicit assumptions and continue. Never invent peripheral capabilities, pin assignments, timing limits, flash/RAM capacity, electrical tolerances, protocol behavior, certification requirements, or production volumes.

Build the Project Baseline

Capture the following before decomposing work:

1. Product purpose, users, operating environment, and definition of success.
2. In-scope and out-of-scope behavior for the target release.
3. Hardware status: concept, evaluation board, prototype, EVT, DVT, PVT, or released board.
4. Processor, memory, clocks, power domains, external devices, debug access, and boot/update path.
5. Interfaces and protocols, including voltage levels, direction, bandwidth, latency, framing, ownership, and error behavior.
6. Software constraints: language, vendor SDK/HAL, RTOS or Linux, bootloader, libraries, coding rules, and toolchain.
7. Quantified budgets: CPU, RAM, flash, stack, bandwidth, boot time, latency, power, storage endurance, and timing margin.
8. Delivery constraints: dates, staffing, hardware availability, dependencies, compliance, manufacturing, and field-update expectations.

Use assets/project-profile.yaml as a reusable intake form when the project context is incomplete.

Produce the Plan

Follow this order so later decisions are traceable to earlier constraints:

1. Define requirement IDs and measurable acceptance criteria. Separate MVP, later releases, and exclusions.
2. Map hardware resources and identify electrical or timing risks before assigning firmware work.
3. Specify peripheral configuration at the level needed for implementation and review.
4. Choose system architecture and concurrency model from data flow, timing, memory, and failure-containment needs.
5. Define module ownership and interfaces across BSP, drivers, services, protocols, application logic, diagnostics, and update/boot paths.
6. Define state machines for lifecycle, communication, update, and recovery behavior where state is observable or safety-relevant.
7. Define fault detection, containment, recovery, persistence, and diagnostic evidence.
8. Design debugging and testability into the system before implementation tasks are scheduled.
9. Build requirement-to-design-to-test-to-risk traceability.
10. Decompose milestones into demonstrable vertical slices with entry criteria, exit criteria, dependencies, estimates, owners, and contingency.
11. Add production, security, compliance, sourcing, and field-service risks appropriate to the product.

Read references/planning-dimensions.md for the required content and review questions for all twelve dimensions. Read references/architecture-decisions.md when selecting execution, layering, data-flow, or state-machine patterns. Read references/verification-production.md when defining tests, fault injection, release gates, or factory readiness.

Enforce Engineering Traceability

Use stable identifiers in substantial plans:

• REQ-nnn: functional and non-functional requirements.
• IF-nnn: electrical, software, or protocol interface contracts.
• DEC-nnn: architecture decisions and rejected alternatives.
• TEST-nnn: verification cases and acceptance tests.
• RISK-nnn: technical, schedule, supply, production, security, or field risks.
• GATE-nnn: milestone exit gates.

For each requirement, identify the responsible component, verification method, pass criterion, and associated risks. Mark unsupported claims and unresolved interface contracts. Do not use “complete,” “stable,” or “production-ready” as acceptance criteria without measurable evidence.

Make the Schedule Executable

Estimate work from dependencies and uncertainty, not from a desired date alone. Separate engineering effort from calendar duration. Include board lead time, lab access, integration wait states, review, defect fixing, regression, documentation, and contingency.

Prefer vertical milestones that demonstrate an end-to-end behavior on target hardware. Each milestone must include:

• deliverable and observable demo;
• entry and exit criteria;
• dependencies and critical path;
• owner role and estimated engineering days;
• test evidence to retain;
• fallback or de-scope option.

For intern or junior plans, distinguish guided tasks from independent ownership. Schedule onboarding, toolchain setup, datasheet reading, design review, code review, lab mentoring, and rework. Do not assign sole ownership of safety, bootloader security, hardware sign-off, EMC closure, or release approval to an intern.

Write the Deliverable

Use the user's language. Keep register names, protocol names, identifiers, and units technically exact. Start from assets/project-plan-template.md for a full plan, but remove irrelevant prompts and empty sections. A full plan must retain section markers EP-01 through EP-12 even if one section is explicitly not applicable.

Tailor depth to project maturity:

• At concept stage, emphasize unknowns, feasibility experiments, budgets, and hardware/software contracts.
• At implementation stage, emphasize interfaces, task ownership, integration order, instrumentation, and unit/component tests.
• At validation stage, emphasize traceability, stress and fault injection, release criteria, manufacturing, and field recovery.

Use references/rs485-w5500-example.md only as a structural example for an industrial MCU gateway. Do not copy its component choices into unrelated projects.

Validate the Result

Before delivery, perform a consistency pass:

1. Check that every requirement has a testable outcome.
2. Check pin, clock, memory, bandwidth, timing, power, and storage assumptions against available evidence.
3. Check ISR, DMA, task, queue, lock, and buffer ownership for race, overflow, and deadlock risks.
4. Check every timeout and retry path for a terminal outcome.
5. Check watchdog design for independent fault detection and post-reset diagnosis.
6. Check update and configuration paths for interrupted writes, rollback, compatibility, and recovery.
7. Check that milestones integrate on target hardware early enough to expose cross-layer defects.
8. Check that production risks have owners, triggers, mitigations, and verification evidence.

When the output is written to a Markdown file, run:

python3 scripts/validate_plan.py path/to/project-plan.md --strict

Resolve validation failures before reporting completion. Explain warnings that remain intentionally open.