agent instructions: include coderabbit and other guidance

.apm/instructions/backend.instructions.md

@@ -3,17 +3,40 @@ description: "Go backend coding standards for Sippy"
 applyTo: "**/*.go"
 ---
 
-* When adding or updating APIs, **use HATEOAS** in responses to support discoverability and consistent client interaction.
 * Follow idiomatic Go practices.
+* Choose names carefully using concise but appropriately descriptive words; in the scope of a
+  package, a name need only describe its function relative to that package. Provide docstring for
+  every package-level name explaining _why_ it exists and describing any parameter whose purpose is
+  not completely obvious from name and context.
+* Keep packages, structs, and methods focused on a single clear conceptual "chunk":
+  a package should represent one cohesive concept, a struct should represent a single entity
+  in the scope of its package, and a method should operate on a single level of abstraction.
+  Prefer descriptive names that evoke a specific concept (e.g., "TestResultAggregator" not
+  "Manager"). Avoid generic names like "Manager", "Handler", "Util" without specific context,
+  and method names that don't indicate what they do (e.g., "Process", "Handle", "Do").
+  Structs with more than about 7 top-level fields should be refactored into focused sub-types.
+* When adding or updating APIs, **use HATEOAS** in responses to support discoverability and consistent client interaction.
 * Use `k8s.io/apimachinery/pkg/util/sets` (e.g. `sets.New[string]()`) to deduplicate or collect 
   unique strings. Do not use `map[string]bool` as a hand-rolled set.
 * Prefer structured logging where it makes sense; particularly for names and IDs, and often for
   counts, a log.WithField() call is preferred over formatting values into a string.
-* After making changes, always run `gofmt -w` on modified files to ensure proper formatting.
 * When modifying any data provider (BigQuery or PostgreSQL), ensure **parity between both implementations**. Changes to query logic, filtering, or returned data in one provider must be reflected in the other.
 * **Timestamps and dates**: Use proper types, never epoch integers.
   - PostgreSQL columns: use `TIMESTAMP WITH TIME ZONE` for timestamps and `DATE` for date-only values. All timestamps are UTC.
   - Go structs: use `time.Time` for timestamps. Use `civil.Date` (`cloud.google.com/go/civil`) for date-only values (e.g., GA dates, development start dates). Do not use `string` for date or timestamp fields; let JSON marshaling produce the correct format.
   - API responses: timestamps serialize as RFC 3339 strings, dates as `YYYY-MM-DD` strings. Never return epoch millisecond integers. Never manually format with `time.Format()` into a string field.
   - Materialized views: project timestamp columns directly from the source table. Do not convert to epoch with `EXTRACT(epoch FROM ...)`.
   - GORM model tags: include `gorm:"type:date"` on date-only columns so GORM and migrations use the correct PostgreSQL type.
+* Check `pkg/util/` for existing helper functions before adding inline utility logic.
+  Avoid calling the same utility function multiple times with identical arguments in the
+  same code path.
+* Never ignore returned errors as `_` without clear justification. Errors should be wrapped
+  with context using `fmt.Errorf` with `%w`. Avoid `panic()` except in `init()` or fatal
+  conditions. Check for nil before dereferencing pointers.
+* **Never** concatenate or format SQL queries with values directly from user input. Always use
+  placeholders for parameters in queries, preferably named (`@Name`).
+* Structs used with GORM that have fields not backed by database columns (such as computed or
+  API-only fields) must include the `gorm:"-"` tag to explicitly exclude them from GORM operations.
+  BigQuery struct fields must have `bigquery:"column_name"` tags that exactly match the BigQuery
+  query result schema names, whether from table columns or aliases (give computed fields aliases).
+* After making changes, always run `gofmt -w` on modified files to ensure proper formatting.

.apm/instructions/docs.instructions.md

@@ -21,3 +21,7 @@ applyTo: "**"
 * Documentation and code belong in the same PR; never treat a docs update
   as a follow-up task.
 * Do not use em dashes when writing docs. Use commas, parentheses, or periods instead.
+* Files under `pkg/**/jobrunscan**/`, `pkg/**/jobrunannotator**/`, `pkg/api/jobartifacts/**`, and
+  `sippy-ng/src/component_readiness/JobArtifactQuery.js` are part of the symptoms feature documented
+  in `docs/features/job-analysis-symptoms.md`. Update this document when there are changes to data
+  models, API surface, or data flow in the symptoms feature.

.apm/instructions/frontend.instructions.md

@@ -3,21 +3,33 @@ description: "React/Material-UI frontend guidelines for Sippy"
 applyTo: "sippy-ng/**"
 ---
 
+* The frontend uses `npm`. If you must install or update any dependencies, always use the `--ignore-scripts` flag.
 * After making changes, always run formatting and linting to maintain consistency:
 
-```bash
-npx eslint . --fix
-npx prettier --write .
-```
+  ```bash
+  npx eslint . --fix
+  npx prettier --write .
+  ```
 
 * Prefer functional components and React hooks over class components.
 * Keep UI elements consistent with Material-UI standards.
-
-The frontend uses `npm`. If you must install or update any dependencies, always use the `--ignore-scripts` flag.
-
+* Avoid nested ternary expressions in JSX. When there are more than two
+  branches, use if/else if chains, early returns, or a lookup object instead.
+  A single ternary is fine; nesting ternaries makes code hard to follow.
+* Before adding date/time formatting, duration calculations, or string
+  utilities inline, check `sippy-ng/src/helpers.js` for existing functions
+  like `relativeDuration`, `safeEncodeURIComponent`, etc. Prefer reusing
+  existing helpers over reimplementing similar logic.
+* React components with extensive inline CSS should use the `useStyles` pattern.
+  Inline style objects with more than 3-4 properties should be extracted to
+  `useStyles()` or styled components. Inline styles are acceptable for simple,
+  dynamic values (e.g., width based on props).
 * **Timestamps and dates from the API**:
   - Timestamps arrive as RFC 3339 strings (e.g., `"2024-06-27T15:30:00Z"`), not epoch millisecond integers. Use `new Date(value)` or `Temporal.Instant.from(value)` to parse them.
   - Dates arrive as `YYYY-MM-DD` strings (e.g., `"2024-06-27"`). Use `Temporal.PlainDate.from(value)` for date arithmetic.
   - For MUI DataGrid timestamp columns, use `type: 'date'` with a `valueGetter` that returns a `Date` object. Do not return epoch milliseconds from `valueGetter`.
   - For filter values sent to the API, use ISO 8601 strings (e.g., `new Date(...).toISOString()`), not epoch millisecond integers.
   - For day-level bucketing or date arithmetic, prefer `Temporal.PlainDate` over `Date` with manual millisecond math.
+* Non-trivial modifications to frontend logic must include unit test coverage.
+  If a function is hard to test, consider refactoring to separate pure logic
+  from side effects. 

.apm/instructions/general.instructions.md

@@ -20,5 +20,6 @@ The system consists of:
 * A **Go-based API backend**.
 * A **React/Material-UI frontend** (located in `sippy-ng`).
 * Data sources including **PostgreSQL**, and **BigQuery**
+* A **headless daemon** for asynchronous processing
 
 Favor clarity and maintainability over cleverness. Comments should be minimal, helpful, and explain the "why" not the "what".

.apm/instructions/query.instructions.md

@@ -0,0 +1,14 @@
+---
+description: "Guidelines for BigQuery and SQL query-building code"
+applyTo: "pkg/**/query/**"
+---
+
+* Abbreviations should be expanded on first use, for example Common Table Expression (CTE) and
+  Materialized View (matview). "SQL" is exempt from this rule.
+* BigQuery and SQL query-building code should have inline comments explaining the
+  purpose of each major query section (CTEs, JOINs, window functions, WHERE clauses).
+* Functions that construct queries must stay under 200 lines; extract sub-queries or
+  CTEs into helper functions when they grow beyond that.
+* When constructing SQL queries, prefer using a format string and/or multi-line string rather than
+  concatenation of short strings; and always use placeholders for parameters.
+

.apm/instructions/testing.instructions.md

@@ -22,3 +22,11 @@ applyTo: "**/*_test.go"
   interface.
 * Prefer **table-driven tests** with descriptive case names. Search the same package for
   existing test patterns before writing new ones.
+* New or modified functionality must include test coverage:
+  new Go functions and methods should have corresponding unit tests,
+  bug fixes should include a regression test that fails without the fix,
+  and pure functions (no DB/external dependencies) should always be tested.
+  If a function is hard to test, consider refactoring it into simpler functions 
+  (disentangle separate conceptual chunks).
+  Exceptions: trivial changes (renaming, formatting, comments), generated code or
+  configuration-only changes, and refactors already covered by existing tests.