Implementation Observations
Purpose
Section titled “Purpose”Structured observation log for the Item Image Upload system design session. Captures process patterns, content patterns, friction points, and insights for future skill development.
This file has two parts:
- Pre-execution observations — captured during the kickoff definition session (human + agent dialog).
- Execution observations — appended by the implementing agent during document production.
After the design is complete, an improvement-analyzer agent will consume this log to propose new skills and templates.
Categories
Section titled “Categories”Use these categories when logging observations:
- PROCESS — How work was structured, sequenced, or decided.
- CONTENT — Patterns in the produced artifacts (repeatable structures, templates).
- FRICTION — Where the agent got stuck, backtracked, or lacked guidance.
- MISSING — Skills, templates, or conventions that didn’t exist but should.
- INSIGHT — Non-obvious lessons or surprising outcomes.
Pre-Execution Observations
Section titled “Pre-Execution Observations”OBS-001 — PROCESS: Iterative kickoff dialog
Section titled “OBS-001 — PROCESS: Iterative kickoff dialog”The system design kickoff required 8 rounds of Q&A between the user and the agent before the task was well-defined enough to execute. The dialog followed a consistent pattern:
- Agent reads the goal file and all references.
- Agent summarizes understanding and asks clarifying questions.
- User answers and provides additional guidance.
- Repeat until no further questions.
This pattern is not captured in any existing skill. The closest is complex-project-definition-and-planning, but that targets design sessions with decision rounds, not the pre-work of defining the deliverable structure for a design session.
OBS-002 — PROCESS: Deliverable structure emerged from dialog, not from a template
Section titled “OBS-002 — PROCESS: Deliverable structure emerged from dialog, not from a template”No existing template defines the deliverable set for a system-level design. The structure (system-level docs + per-actor docs) was negotiated during the dialog. The user restructured the initial proposal (one doc per deliverable) into a more cohesive layout (per-actor consolidation). A template or checklist for “what does a system design contain?” would have accelerated this.
OBS-003 — PROCESS: Design decisions were made during kickoff, not during execution
Section titled “OBS-003 — PROCESS: Design decisions were made during kickoff, not during execution”Seven design decisions (TD-01 through TD-07) were made before any document was written. These decisions were architectural choices (where does fetch-and-store happen, who generates presigned credentials, what does the BFF depend on). The pattern: the agent identified decision points as questions, the user resolved them, and the agent recorded them in the index. This is distinct from the decision-log skill’s round protocol, which assumes decisions emerge during design authoring.
OBS-004 — CONTENT: Scenario inventory as a planning artifact
Section titled “OBS-004 — CONTENT: Scenario inventory as a planning artifact”The scenario inventory (S1–S7) was defined in the index as a planning step before any sequence diagram was drawn. Each scenario maps to one or more use case IDs and has a one-line description of the actor interactions. This “scenario inventory” pattern is reusable — it bridges use case analysis and sequence diagram production.
OBS-005 — CONTENT: Actor dependency diagram as a structural artifact
Section titled “OBS-005 — CONTENT: Actor dependency diagram as a structural artifact”The user requested an actor dependency diagram showing which actor initiates interactions with which. This is not a C4 diagram or a class diagram — it’s a simpler block diagram focused on dependency direction. The diagram surfaced a design insight (BFF does not depend on AWS Resources) that led to a decision correction. This artifact type is not in any existing template.
OBS-006 — PROCESS: Prior work declared informative, not binding
Section titled “OBS-006 — PROCESS: Prior work declared informative, not binding”The user explicitly declared that prior design work was informative only. This framing prevented the agent from treating earlier decisions as constraints. The pattern: when a project has prior design iterations, the kickoff should explicitly state which artifacts are binding vs. informative.
OBS-007 — CONTENT: Per-actor document structure
Section titled “OBS-007 — CONTENT: Per-actor document structure”Each actor document has exactly 4 sections: Requirements, Interfaces, State, Modules. This structure emerged from consolidating the original per-deliverable layout. It groups all information about an actor in one place, making it easier for an implementation agent to work on one actor at a time. This is a reusable template pattern for system designs with multiple actors.
OBS-008 — PROCESS: OAM requirements as a standard deliverable
Section titled “OBS-008 — PROCESS: OAM requirements as a standard deliverable”The user specified FCAPS (Fault, Configuration, Performance, Security, Accounting Management) as a standard framework for OAM requirements. This is borrowed from telecommunications network management and applied to SaaS systems. No existing skill or template covers this. It could become a reusable template for any system design.
OBS-009 — PROCESS: Risks/assumptions as an explicit deliverable
Section titled “OBS-009 — PROCESS: Risks/assumptions as an explicit deliverable”Risks, obstacles, and assumptions (including data migration concerns) were called out as a separate deliverable. The user emphasized that these may be out of scope for implementation but must be recorded for project-level tracking. This “record now, address later” pattern prevents information loss between design and implementation phases.
OBS-010 — MISSING: No skill for “system-level design”
Section titled “OBS-010 — MISSING: No skill for “system-level design””The existing skills cover project planning (project-planning), complex project definition (complex-project-definition-and-planning), and design documents (design-document). None covers the specific workflow of producing a system-level design: actor identification, dependency mapping, scenario inventory, per-actor decomposition, OAM requirements, and phasing. This is a distinct skill.
Execution Observations
Section titled “Execution Observations”OBS-011 — PROCESS: Source document updates as prerequisite to design authoring
Section titled “OBS-011 — PROCESS: Source document updates as prerequisite to design authoring”Date: 2026-03-27
The TD-01 fetch-and-store decision resolved a previously deferred scoping decision (SD-01). Before writing design documents, 6 source files needed updating (feature spec, use case spec, scoping, decision log, use-case-definition index, system-design index). Doing this first ensured the requirements document derived from corrected source material. A checklist or skill for “propagate a decision resolution across source documents” would have made this systematic rather than manual.
OBS-012 — CONTENT: Requirements document as traceability hub
Section titled “OBS-012 — CONTENT: Requirements document as traceability hub”Date: 2026-03-27
The requirements.md document became the traceability hub: every requirement links to source use cases and design decisions, and every subsequent document (scenarios, actor specs) references requirement IDs. Writing it first was essential — the dependency order prescribed in the kickoff was correct. A template with pre-structured traceability columns (ID, Requirement, Source) would accelerate future system designs.
OBS-013 — CONTENT: Scenario DRY pattern via ref blocks
Section titled “OBS-013 — CONTENT: Scenario DRY pattern via ref blocks”Date: 2026-03-27
PlantUML ref blocks allowed scenarios S5, S6, and S7 to reference S1’s
upload sequence without duplication. This kept diagrams focused on what’s
unique to each scenario (entry point, form context) while avoiding repetition.
The PlantUML guide does not document ref blocks — this should be added.
OBS-014 — INSIGHT: Presigned POST vs PUT as system-level decision
Section titled “OBS-014 — INSIGHT: Presigned POST vs PUT as system-level decision”Date: 2026-03-27
The choice of presigned POST over presigned PUT affects three actors (SPA form construction, Backend credential generation, AWS S3 policy). It was correctly identified as a system-level design decision (TD-08) rather than an implementation detail in a single actor. This pattern — “if a decision affects the contract between two or more actors, it’s a system-level decision” — should be documented as guidance for future design sessions.
OBS-015 — PROCESS: Actor spec 4-section structure is effective
Section titled “OBS-015 — PROCESS: Actor spec 4-section structure is effective”Date: 2026-03-27
The per-actor 4-section structure (Requirements, Interfaces, State, Modules) worked well. Requirements trace to scenarios; interfaces define the contracts; state clarifies what the actor manages; modules identify concrete implementation units. This structure should be templated for future system designs. The BFF spec was simplest (stateless proxy), the SPA spec was densest (state machine, 19 components), and the AWS spec focused on configuration over behavior — the template accommodated all three naturally.
OBS-016 — FRICTION: No existing template for FCAPS OAM requirements
Section titled “OBS-016 — FRICTION: No existing template for FCAPS OAM requirements”Date: 2026-03-27
Writing oam-requirements.md required structuring from scratch. The FCAPS model (Fault, Configuration, Accounting, Performance, Security) provided the framework, but mapping system design concerns to FCAPS categories required judgment. A template with example entries per category would reduce friction for future designs.
OBS-017 — CONTENT: Migration concerns bridge design and implementation
Section titled “OBS-017 — CONTENT: Migration concerns bridge design and implementation”Date: 2026-03-27
The risks-and-assumptions document’s migration section (M-001 through M-004) captured concerns that are out of scope for the design but critical for implementation planning: existing imageUrl values, CSV import behavior, infrastructure deployment ordering. These are the kind of items that get lost between design and implementation. A dedicated “migration concerns” template section in the design-document skill would prevent this.
OBS-018 — PROCESS: PlantUML validation via MCP tool was efficient
Section titled “OBS-018 — PROCESS: PlantUML validation via MCP tool was efficient”Date: 2026-03-27
All 8 diagrams (7 scenarios + 1 phasing) were validated via the PlantUML MCP tool before writing. Every diagram passed on first attempt, confirming that the PlantUML guide conventions (hide footbox, discrete activation blocks, no curly braces in messages, return for deactivation) are sufficient to avoid common pitfalls. The validation step took negligible time compared to diagram authoring.
Implementation Planning Observations
Section titled “Implementation Planning Observations”OBS-019 — CONTENT: Phasing benefits from distinguishing design vs. deploy dependencies
Section titled “OBS-019 — CONTENT: Phasing benefits from distinguishing design vs. deploy dependencies”Date: 2026-03-30
When refining the phasing document, two distinct dependency types emerged: design dependencies (the downstream phase needs an API contract or library artifact to write code) and deploy gates (the upstream phase must be live and verified before the downstream phase can complete integration testing). Visualizing these with different colors in the dependency diagram immediately revealed that Phase 3b (BFF cookie signing) has no design dependency on the Backend — only on Phase 1’s signing key. This insight shortened the read-path track by allowing 3b to start in parallel with all Backend phases. The distinction should be a standard part of any phasing analysis.
OBS-020 — PROCESS: Cross-referencing product specs against system design catches stale text
Section titled “OBS-020 — PROCESS: Cross-referencing product specs against system design catches stale text”Date: 2026-03-30
A systematic comparison of the feature requirements (GEN::MEDIA::FR-0001
through FR-0020), use case scenarios, and system design documents revealed
6 inconsistencies that survived the original audit. Most were stale text in
upstream product specs that had not been updated when system design decisions
(TD-01, TD-05) changed the architecture. Examples: FR-0002 still mentioned
“external URL reference” as a processing path after TD-01 eliminated it;
REF::ITM::0006::0005.FS claimed CSV round-trip was preserved when TD-05
would break it. A checklist for “propagate design decisions back to source
product specs” would catch these systematically.
OBS-021 — CONTENT: Risks document belongs at the project level, not inside results/
Section titled “OBS-021 — CONTENT: Risks document belongs at the project level, not inside results/”Date: 2026-03-30
The risks-and-assumptions.md document was originally placed inside
system-design/results/ alongside actor specifications. During planning review,
it became clear that risks and migration concerns (M-001 through M-004) are
project-level concerns that span design and implementation — they are not
“results” of the design session. Moving the file up to system-design/ better
reflects its scope. Future system design templates should place
risks/assumptions at the project level from the start.
OBS-022 — INSIGHT: FR renumbering is expensive due to cross-reference density
Section titled “OBS-022 — INSIGHT: FR renumbering is expensive due to cross-reference density”Date: 2026-03-30
Attempting to renumber functional requirements (to make Item-Specific appear before CDN Access Control) cascaded across 8+ files with dozens of cross-references. The cost of updating all references exceeded the benefit of sequential numbering. The pragmatic resolution was to reorder the document sections without changing IDs. Lesson: treat FR IDs as stable identifiers (like database primary keys), not as ordering indicators. Add new requirements at the end of the sequence regardless of logical grouping.
Copyright: (c) Arda Systems 2025-2026, All rights reserved
Copyright: © Arda Systems 2025-2026, All rights reserved