blocksense-v3.7-open-questions.md

Urban Dossier NYC v3.7 - Open Questions And Confirmed Decisions

Purpose: collect what we have already aligned on, what is explicitly deferred, and what still needs a decision before the next engineering doc revision.

Date: 2026-04-11 Scope: backend product logic, report logic, radius logic, building-signal handling, and frontend/backend interface assumptions

---

1. What This Document Is For

This is not the final engineering document.

It exists to prevent the team from re-opening already-settled questions while we continue refining:

• report generation
• overview/detail split
• radius-dependent logic
• building-level signal handling
• frontend/backend handshake

Use this document as the current decision ledger for v3.7 planning.

---

2. Confirmed Product Direction

These items are already aligned well enough to treat as current working decisions.

2.1 Overview vs detail

The current product interpretation is:

• overview helps the user locate problem areas on the map
• detail performs the real local analysis after a click
• the local report is generated only in detail

Overview does not generate a report.

2.2 Report trigger

The current expected interaction is:

1. user clicks a point on the map
2. user chooses:
   • radius
   • priority order
3. user clicks a confirm/generate button
4. backend runs the full detail pipeline
5. backend returns the final report

This means:

• changing controls does not have to trigger LLM generation immediately
• the confirmed detail request is the report-generation trigger

2.3 User-selectable radius options

The currently agreed radius set is:

• 200m
• 500m
• 1000m

These should be treated as product-level options, not arbitrary free-form numeric input.

2.4 User preference role

User priority ranking affects:

• detail priority weights
• detail priority_actions
• report emphasis

User priority ranking does not affect:

• overview layer generation
• overview map permutations

Overview should stay:

• one overall map
• one map per single category button

2.5 Building handling choice

Current preferred choice: Option 4A

Interpretation:

• building-related signals should be represented as a separate detail section
• they do not have to be one of the user-drag main categories
• they should remain visible and explorable in detail mode even if the main user categories are only safety / traffic / facilities

This allows:

• cleaner building-specific reasoning
• future building markers / styling in the frontend
• less confusion between "area-level pressure" and "this nearby building has an issue"

2.6 Report style direction

The report must be oriented toward:

• concrete conclusions
• concrete local priorities
• concrete evidence-backed interpretation

It must not read like:

• a generic neighborhood summary
• a metric dump
• a bland restatement of counts

However, the report prompt should not over-script the exact paragraph sequence or force rigid canned wording.

The model should be guided to:

• write specific conclusions
• adapt to the actual evidence
• describe both positive and negative findings honestly
• avoid assuming the answer must sound alarming

In other words:

• direction must be strict
• writing surface can stay flexible

2.7 Radius must be explicitly named in the report

The detail report should clearly state:

• selected point
• selected radius
• some basic context such as borough / ZIP if available

This is required so the user does not confuse:

• point-level building findings
• radius-level local context
• ZIP-level service proxies

---

3. Proposed Radius Logic For Review

This section captures the current backend proposal that still needs one more team review, but is already stable enough to draft against.

3.1 Signals that should strictly follow user-selected radius

These should use the chosen radius directly:

• collisions
• rodent inspections
• 311 complaints
• restaurant inspections
• LinkNYC
• public toilets
• street trees
• other point/facility context datasets

Recommended method:

• bbox coarse filter
• haversine exact filter
• aggregate within selected radius

3.2 Signals that should use a dedicated building radius

Building-linked signals should not expand all the way to 1000m.

Recommended rule:

• building_radius = min(selected_radius, 250m)

So:

• if selected radius is 200m, building radius is 200m
• if selected radius is 500m, building radius is 250m
• if selected radius is 1000m, building radius is still 250m

Applies to:

• housing violations
• AEP
• other future building-specific datasets

3.3 Signals that should not follow the user radius

These should remain area/ZIP context proxies:

• EMS
• Fire
• future ZIP/CD aggregate service metrics

Report language should make clear that these are:

• area-level context
• not exact point-radius measurements

3.4 Parks / large polygon handling

First-pass proposal:

• use radius-based access / nearby proxy for point interaction
• allow acreage / polygon measures to stay approximate for now
• explicitly mention approximation in data_gaps when needed

This remains a provisional rule and may be revised when frontend and data processing are clearer.

3.5 Normalization concern

Changing radius changes raw counts.

Therefore, severity should not rely on raw counts alone.

Current preferred direction:

• long-term: build radius-specific baselines for 200m, 500m, 1000m
• interim fallback: use density or radius-normalized scaling to reduce trivial count inflation

This is still an engineering item to be finalized.

---

4. Confirmed Report Logic Direction

4.1 Report should be generated from deterministic outputs

The model should receive already-computed:

• priority_actions
• why_now
• current_state
• evidence_table
• data_gaps
• target context
• selected radius
• selected priority order

The model should not be the source of:

• ranking
• trend detection
• factual selection

4.2 Prompt direction

Prompt guidance should require the model to:

• produce concrete local conclusions
• lead with what should be prioritized
• explain why those issues rose to the top
• mention the selected radius explicitly
• include basic local context
• stay faithful to actual evidence whether results are good, bad, mixed, or sparse

Prompt guidance should avoid:

• forcing a fake alarmist tone
• forcing a fake optimistic tone
• forcing one rigid paragraph template regardless of evidence
• turning the report into a generic summary

4.3 Concrete-conclusion standard

The report should aim for statements like:

• "Within the selected 500m radius, street-safety pressure remains elevated relative to baseline and should be checked first."
• "The strongest nearby building pressure comes from serious housing violations within the building-radius window, not from broader facilities scarcity."
• "ZIP-level emergency response metrics suggest service pressure in the surrounding area, but they should not be interpreted as exact point-level response time."

The report should avoid statements like:

• "There are many data points nearby."
• "The area has some issues and some amenities."
• "Overall things look mixed."

---

5. Building-Related Output Plan

This section is not about frontend color or rendering decisions.

It is about what the backend should be prepared to output so the frontend can later decide how to style it.

5.1 Overview-level building output

Backend should eventually support an aggregated building-stress signal for overview cells, for example:

• building_stress_score
• building_signal_count
• building_stress_level

This supports future map styling without forcing the backend to decide colors.

5.2 Detail-level building output

Backend should support per-building or near-building detail objects such as:

• bbl
• bin
• latitude
• longitude
• flag_type
• severity
• label
• score_hint
• summary

These can feed:

• markers
• building cards
• side panels
• future styling layers

5.3 Important boundary

The backend should decide:

• score
• level
• flag
• object identity

The frontend should decide:

• color
• icon
• opacity
• layering
• rendering style

This separation is intentional and should remain.

---

6. Deferred Topics

These topics are real, but they are not blockers for the next report/detail design step.

6.1 Watchlist

Watchlist was discussed previously as batch reuse of detail logic.

At this stage it is deferred from the current decision cycle because:

• the current main interaction is point click + confirm report
• the team is still finalizing detail/report logic
• watchlist is not necessary to settle the current radius/report questions

Current temporary understanding:

• watchlist remains a batch/automation mode
• it does not drive the current report design decision
• it can be revisited after detail/report logic stabilizes

6.2 Final frontend building visual design

Frontend styling for buildings and map layers is still pending.

We should not block backend scoring/output structure on those UI choices.

---

7. Open Questions Still Needing Decisions

These remain open after the current discussion.

7.1 Radius-specific baseline strategy

Need to decide:

• do we build true separate baselines for 200m, 500m, and 1000m now
• or do we ship a density-normalized interim approach first

7.2 Parks / polygon approximation rule

Need to decide:

• exact first-pass method for parks and other large polygons
• whether acreage stays approximate in v3.7
• how explicitly to surface that approximation in data_gaps

7.3 Overview context inside the detail report

Possible direction:

• include a lightweight overview_context block for the clicked point's containing cell

Need to decide:

• is this in scope for the next report revision
• or is it postponed until after the first detail report pass is stable

7.4 Basic context fields in the detail report

Currently expected:

• selected point
• selected radius
• borough if available
• ZIP if available
• active priority order

Need final confirmation that this is the minimum required context block.

7.5 Future building score output shape

Need to decide:

• whether building-level outputs should always include a normalized score_hint
• whether backend should emit both numeric score and categorical severity
• how much of that should be considered stable contract vs experimental

7.6 Frontend preview behavior before report generation

Need to confirm:

• does frontend show a preview state before the user clicks confirm
• or does it only show the final generated detail result after confirmation

This affects:

• when deterministic detail computation runs
• whether report generation is the same request or a later request

---

8. Immediate Next-Step Recommendation

Before the next full engineering doc revision, the team should next confirm:

1. radius-specific baseline strategy
2. parks/polygon approximation approach
3. whether overview_context enters the first detail report version
4. the minimum required context block for the report
5. whether frontend has a preview stage before confirm

Everything else in this document can already be treated as current working direction.

---

9. Short Summary

Current stable direction:

• overview locates problem areas
• detail is where the real report happens
• user confirms radius + priority order before report generation
• radius options are 200 / 500 / 1000m
• building signals should live as a separate detail section
• report style should aim for concrete conclusions while still allowing the LLM freedom to write naturally from the real evidence

Current deferred topic:

• watchlist

Current main unresolved items:

• radius-specific baselines
• parks/polygon handling
• whether to add overview context into the detail report
• exact stable building-output contract