Maintenance Backlog and Low-Priority Fixes

Table of Contents

• 1. Purpose
• 2. Current Tracker Source
• 3. Warning Cleanup Categories
• 4. Suggested Workflow
• 5. Prioritization Policy
• 6. Sandbox Policy
• 7. Runtime Observability Backlog
  • CFD Reader Guidance and Practical Use
    • What To Extract Before Changing A Case
    • Practical CFD Troubleshooting Pattern

This page tracks non-blocking technical debt items (warnings cleanup, refactors, and quality-of-life fixes) that are safe to address incrementally.

1. Purpose

Use this page for:

• compiler warning cleanup queues,
• low-priority style/consistency fixes,
• non-urgent tooling/docs polish tasks.

Do not use this page for urgent correctness/security issues.

2. Current Tracker Source

Primary warning tracker location:

• logs/doxygen.warnings (generated by make build-docs)

For compiler/runtime warning campaigns, track status directly in this page.

3. Warning Cleanup Categories

Current warning clusters include:

• pointer/type mismatches,
• potentially uninitialized variables,
• format-string and buffer safety issues,
• unused code/variables,
• logical/style inconsistencies,
• PETSc deprecations.

These categories should be fixed in small, reviewable batches.

4. Suggested Workflow

1. Pick one warning category and one module area (for example, src/io.c).
2. Fix warnings without behavior changes.
3. Rebuild and confirm warning deltas.
4. Update this page with resolved/remaining counts.
5. Commit as maintenance-only patch.

5. Prioritization Policy

• Correctness-affecting warnings (uninitialized, format overflows, type mismatches) first.
• Pure style/unused warnings later.
• Keep each patch narrowly scoped to reduce regression risk.

6. Sandbox Policy

• sandbox/ is retained as optional developer scratch space.
• Treat everything in sandbox as non-production unless promoted.
• Stable outcomes should be moved into config/, examples/, scripts/, or docs/.

7. Runtime Observability Backlog

Potential low-priority observability improvements worth revisiting:

• move the local wrapper stream log out of runs/<run_id>/logs/ so it is not affected by solver-side log-directory recreation; scheduler/ is the existing precedent for batch stdout/stderr.
• add an optional compact per-step summary CSV that consolidates already-available signals such as momentum pseudo-iterations/final residual, Poisson iterations/final residual, continuity/divergence, and particle health counters.
• add an optional boundary-flux summary CSV for inlet/farfield/outlet totals and conservation error when boundary-condition debugging becomes a repeated workflow need.
• add cadence-based field-extrema summaries (P, |Ucat|, Psi, diffusivity) only if users need compact trend logs instead of verbose anatomy/min-max output.
• extend particle metrics only when current Particle_Metrics.log proves insufficient; prefer compact inventory/health summaries over larger particle state dumps.

Observability policy note:

• current runtime coverage is already strong for most runs: momentum convergence, Poisson convergence, continuity metrics, particle metrics, console particle snapshots, and profiling summaries.
• backlog items in this section are primarily convenience or subsystem-specific diagnostics, not missing core health signals.

CFD Reader Guidance and Practical Use

This page describes Maintenance Backlog and Low-Priority Fixes within the PICurv workflow. For CFD users, the most reliable reading strategy is to map the page content to a concrete run decision: what is configured, what runtime stage it influences, and which diagnostics should confirm expected behavior.

Treat this page as both a conceptual reference and a runbook. If you are debugging, pair the method/procedure described here with monitor output, generated runtime artifacts under runs/<run_id>/config, and the associated solver/post logs so numerical intent and implementation behavior stay aligned.

What To Extract Before Changing A Case

• Identify which YAML role or runtime stage this page governs.
• List the primary control knobs (tolerances, cadence, paths, selectors, or mode flags).
• Record expected success indicators (convergence trend, artifact presence, or stable derived metrics).
• Record failure signals that require rollback or parameter isolation.

Practical CFD Troubleshooting Pattern

1. Reproduce the issue on a tiny case or narrow timestep window.
2. Change one control at a time and keep all other roles/configs fixed.
3. Validate generated artifacts and logs after each change before scaling up.
4. If behavior remains inconsistent, compare against a known-good baseline example and re-check grid/BC consistency.