Skip to content

Logging

Plan Metadata

  • Plan type: plan
  • Parent plan: N/A
  • Depends on: N/A
  • Status: documentation

System Intent

  • What is being built: A single parent plan and canonical contract for all logging.
  • Primary consumer(s): Logging sub-plans.
  • Boundary (black-box scope only): Shared logging field contract and links to frontend and backend logging plans.

Logging Summary

  • Frontend summary: React code uses LoggingContextProvider + useLogging() so flow comes from provider scope and logs are emitted at step boundaries.
  • Backend summary: Server code uses shared create_logger({flow}) and then log_event({step, additional?}) for consistent flow step [additional] log lines.

Logging Ideology

  • Log more, not less, for non-trivial flows.
  • Keep one stable flow from start to end of a user/system flow.
  • Treat step as the exact action boundary being executed right now.
  • Use additional for state transitions and I/O context.
  • Avoid redundant success logs; the next step-start log implies prior success.
  • Never log secrets or sensitive user data.

Stage Gate Tracker

  • [x] Stage 1 Mermaid approved
  • [x] Stage 2 I/O contracts approved
  • [x] Stage 3 pseudocode approved or skipped

1. Mermaid Diagram

Reference: .agent/skills/create-mermaid-diagram/SKILL.md

flowchart TD
  Frontend[Frontend Logging Plan - docs/plans/frontend-logging.md]
  Backend[Backend Logging Plan - docs/plans/backend-logging.md]

  classDef unchanged fill:#d3d3d3,stroke:#666,stroke-width:1px;
  classDef updated fill:#ffe58a,stroke:#666,stroke-width:1px;
  classDef deleted fill:#f4a6a6,stroke:#666,stroke-width:1px;
  classDef created fill:#a8e6a3,stroke:#666,stroke-width:1px;

  class Frontend,Backend unchanged;

2. Black-Box Inputs and Outputs

Global Types

LoggingEvent {
  flow: string (required; stable flow name from start to end of a flow)
  step: string (required; current step in the flow)
  additional?: unknown (optional structured state/input/output context)
}

LoggingPlanIndex {
  frontend_plan: "docs/plans/frontend-logging.md"
  backend_plan: "docs/plans/backend-logging.md"
}

API Reference

Frontend API

useLogging() -> FrontendLogger
createLogger(flow: string) -> FrontendLogger

FrontendLogger(payload: {
  step: string
  additional?: unknown
}) -> FrontendLogEvent

LoggingContextProvider(props: {
  flow: string
  fallback?: ReactNode
  children: ReactNode
})

Backend API

create_logger(scope: {
  flow: string
}) -> BackendLogger

BackendLogger(payload: {
  step: string
  additional?: unknown
}) -> Dict[str, str]

Flow: logging-plan-index, N/A

path-name input output/expected state change path-type notes updated
logging-contract.required-fields any logging call LoggingEvent happy path required fields are flow and step; message is intentionally not part of contract
logging-contract.context-payload any logging call with context LoggingEvent additional happy path include system state/input/output context to aid debugging
logging-contract.log-density any non-trivial flow multiple LoggingEvent entries across flow happy path prefer more logs rather than fewer logs to improve AI debugging quality
logging-plan-index.references none LoggingPlanIndex happy path parent plan points to both logging sub-plans

3. Pseudocode for Critical Flows

Not needed...

After all stages are approved, apply .agent/skills/reconcile-plans/SKILL.md to propagate contract updates across linked plans.