yuris/life-service

Fork 0

Weekly Review Analytics & Career Floor Evaluation #30

New issue

Closed

opened 2026-09-22 17:58:58 +00:00 by yuris · 0 comments

yuris commented

2026-09-22 17:58:58 +00:00

Owner

Summary

Implement the weekly review analytics engine (POST /v1/reviews and life review --period week), computing evidence-based metrics with explicit numerator, denominator, and unknown coverage breakdown, evaluating weekday career floor attainment based strictly on recorded qualifying outcome facts (never calendar allocations), tracking task deferral frequency, and generating advisory review flags without mutating calendar objects or task commitments.

Background & Technical Rationale

Productivity software often presents misleading analytics:

Vanity Allocations vs Reality: Counting scheduled calendar blocks as "work completed" creates a dangerous illusion of progress. A user who blocks out four hours for career writing but gets pulled into meetings or procrastinates has not achieved the outcome.
Punishing Observation Gaps: If a user starts using the system on a Wednesday, or takes an off-grid vacation without logging into the app, naive metric engines treat the unobserved days as "zero activity / failed habit," inducing guilt and corrupting historical averages.
Automated Destructive Rescheduling: In response to missed goals, automated tools frequently reschedule or delete tasks without consent.

Life implements a rigorous, mathematically honest analytics model:

Career Floor Attainment (Scenario W12): Life defines a core personal policy default: One meaningful career action per weekday. Attainment requires an explicit qualifying outcome fact (qualifies_career_floor: true or qualifying outcome on an area-career task) logged for that weekday. Allocating a calendar block is NOT attainment.

Mathematical Transparency: Every metric must return a structured tuple:

\{\text{name}, \text{numerator}, \text{denominator}, \text{unknown\_count}, \text{coverage}\}

Epistemic Honesty Regarding Gaps: Days prior to service initialization or intervals without observation are reported as unknown_count, rather than being conflated with zero activity. Zero strictly means observed absence under the stated definition.
Planned Duration vs Actual Effort: Planned block duration (from Radicale VEVENTs) is reported separately from user-reported actual effort (from life_events). If actual duration was omitted in the report, it is tracked as unknown rather than guessed.
Deferral Tracking: Tasks deferred two or more times trigger advisory review prompts (e.g. offer smaller scope, move to someday, retain, or cancel) without automated deletion or reprioritization.
Strictly Advisory & Read-Only: The weekly review endpoint is an analytical read operation. It makes ZERO writes to Radicale and modifies no task states.

Exact Technical References & Specifications

1. Workflows Specification (`docs/technical/workflows.md`)

Section: ## Lifecycle and review (line 37):

| Workflow | Input and reads | Decision and approval | Writes and observable result | Failure path |
|---|---|---|---|---|
| Weekly review | Week, timezone, live tasks/events and journal coverage; optional context/Jev | Compare intended outcomes to recorded outcomes, not allocated hours to effort | Advisory review, evidence-linked patterns and optional separately reviewed proposals | Missing history and context/Jev outages are disclosed; review does not change commitments |

Section: ## Personal policy defaults (lines 44, 48, 50):

- One meaningful career action per weekday. Success requires an explicit qualifying outcome linked to the action and day; allocating a calendar block is not success. Qualification must be user-approved or satisfy a reviewed deterministic rubric, never a model's unreviewed inference.
- Explicit review after two confirmed deferrals of the same item since its last review. External differences do not count as deliberate deferrals without evidence. The prompt can offer smaller scope, queue/someday, retain or cancel; it does not decide automatically.

Policy exceptions are explicit, scoped and recorded with reason if supplied. No guilt-driven messaging, inferred completion, silent deletion or automatic idea promotion. Life-area categories are not diagnoses or rankings of human worth.

Section: ## Weekly analytics (lines 52–56):

Return each metric's numerator, denominator, observation interval and coverage. For example, career-floor attainment is qualifying-outcome weekdays / observed eligible weekdays; days outside service history or with missing outcome observation are reported separately as unknown. Zero means observed absence under the stated definition, not absent records in an unobserved period.

Report confirmed service completions separately from observed external completion differences. Count deferrals only where the event semantics establish deferral. Report planned block duration separately from user-reported actual effort; unknown actual duration is excluded with its count disclosed. Correction-aware totals identify the correction policy and retain links to original evidence. Recommendations and review flags cite inputs and question/model versions, not unsupported causal diagnoses.

2. CLI and API Route & Payloads (`docs/technical/cli-api.md`)

Section: ## Command-to-route table (line 45):

| `life review --period week` | POST /v1/reviews | read |

Section: ## Command payloads and results (lines 92, 104):

| Review | period week; optional anchor_date | metrics {name,numerator,denominator,unknown_count,coverage}, evidence IDs, advisory flags |

Period week means Monday local midnight through next Monday; anchor_date selects the containing week. Agenda defaults require an explicit period; task lists have no implicit deadline cutoff.

Section: ## Error identifiers (line 127):

Non-error warning identifiers: history_incomplete, policy_review_required.

3. Verification Scenario W12 (`docs/technical/verification.md`)

Section: ## Workflow scenarios (line 26):

| ID | Requirement and specification | Input / action | Observable acceptance |
|---|---|---|---|
| W12 | Weekly review (workflows.md#weekly-analytics) | Planned blocks, explicit qualifying outcome, missing observation days | Career floor uses recorded outcome, not allocation; numerator/denominator/unknown coverage disclosed |

What to build

1. Week Interval Resolver (`src/domain/analytics/interval.rs`)

In the configured IANA timezone, determine the weekly review bounds:
- Week start: Monday 00:00:00 local time.
- Week end: Next Monday 00:00:00 local time (exclusive).
- If anchor_date is supplied (e.g. 2026-09-23), compute the Monday–Monday interval containing that date.
- Identify the 5 eligible weekdays (Monday through Friday) in that local interval.

2. Career Floor Attainment Metric Calculator (`src/domain/analytics/career_floor.rs`)

For each of the 5 weekdays:
- Determine service history coverage and outcome observation status (docs/technical/workflows.md:54):
  - Did the user report work outcomes or verify activity for this day?
  - If the day falls outside service history, in an observation gap, or has missing outcome observation, increment unknown_count and record under unknown_days. Missing outcome observation is NEVER punished as a failure.
- If the day has valid outcome observation coverage:
  - Query effective corrected work_block_outcome facts for that date (applying folded timeline corrections from #029, per docs/technical/timeline-consistency.md:164):
    - Check if after_json.qualifies_career_floor == true.
    - Crucial Invariant: Do NOT infer qualification from area-career category membership alone or scheduled attendance; qualification requires explicit user assertion qualifies_career_floor: true or an evaluated deterministic rubric (docs/technical/workflows.md:44).
  - If a qualifying outcome fact exists, increment numerator and increment denominator.
  - If outcome was observed and confirmed no qualifying action occurred, do NOT increment numerator; increment denominator.

Resulting metric structure:

{
  "name": "weekday_career_floor_attainment",
  "numerator": 3,
  "denominator": 4,
  "unknown_count": 1,
  "coverage": {
    "observed_days": ["2026-09-21", "2026-09-22", "2026-09-23", "2026-09-24"],
    "unknown_days": ["2026-09-25"]
  }
}

3. Focus Duration vs Actual Effort Calculator (`src/domain/analytics/duration.rs`)

Query scheduled VEVENT work blocks in the week interval:
- Sum duration of planned focus blocks: \sum \text{planned\_minutes}.
Query effective corrected work_block_outcome facts in the week interval (folding correction chains from #029):
- For each effective outcome:
  - If actual_minutes is not null: add to \sum \text{actual\_minutes}.
  - If actual_minutes is null: increment unknown_count.

Return metric:

{
  "name": "focus_block_effort",
  "numerator": 360,
  "denominator": 450,
  "unit": "minutes",
  "unknown_count": 2,
  "coverage": {"planned_blocks": 5, "reported_blocks": 3, "unreported_blocks": 2}
}

4. Deferral Frequency & Policy Flag Engine (`src/domain/analytics/deferrals.rs`)

Query life_events for task update events representing deferrals (e.g. moving planned_start or updating strength).

Group by task uid:

If a task has been deferred \ge 2 times since its last review, generate an advisory flag:

{
  "code": "policy_review_required",
  "task_id": "itm_task_789",
  "title": "Refactor database migrations",
  "deferral_count": 2,
  "message": "Item deferred 2 times since last review; consider smaller scope, moving to someday, or cancelling",
  "evidence_event_ids": ["evt_def_1", "evt_def_2"]
}

Ensure this generates an advisory flag only: do NOT automatically reschedule, cancel, or delete the task.

5. Axum Handler & CLI Interface (`src/api/reviews.rs`, `src/cli/review.rs`)

Implement POST /v1/reviews:

Request body:

{
  "period": "week",
  "anchor_date": "2026-09-23"
}

Response (HTTP 200 OK):

{
  "schema_version": 1,
  "request_id": "req_rev_123",
  "status": "ok",
  "data": {
    "period": "week",
    "from": "2026-09-21T00:00:00+10:00",
    "to": "2026-09-28T00:00:00+10:00",
    "timezone": "Australia/Brisbane",
    "metrics": [
      {
        "name": "weekday_career_floor_attainment",
        "numerator": 3,
        "denominator": 4,
        "unknown_count": 1,
        "coverage": {
          "observed_days": ["2026-09-21", "2026-09-22", "2026-09-23", "2026-09-24"],
          "unknown_days": ["2026-09-25"]
        }
      },
      {
        "name": "focus_block_effort",
        "numerator": 360,
        "denominator": 450,
        "unit": "minutes",
        "unknown_count": 2,
        "coverage": {"planned_blocks": 5, "reported_blocks": 3, "unreported_blocks": 2}
      }
    ],
    "advisory_flags": [
      {
        "code": "policy_review_required",
        "task_id": "itm_task_789",
        "deferral_count": 2,
        "evidence_event_ids": ["evt_def_1", "evt_def_2"]
      }
    ]
  },
  "warnings": [
    {
      "code": "history_incomplete",
      "message": "Friday 2026-09-25 was unobserved; counted in unknown_count rather than failure"
    }
  ],
  "error": null
}

CLI Command:
life review --period week [--anchor-date YYYY-MM-DD] [--json]
- Renders human-readable summary table and metric ratios, or JSON envelope.

Acceptance Criteria

Career floor metric counts only weekdays with explicit qualifying outcome facts (qualifies_career_floor: true), rejecting scheduled blocks without outcome reports (verifying Scenario W12).
Days prior to service initialization, observation gaps, or days with missing outcome observation are counted under unknown_count and are NOT treated as failure days (Scenario W12, docs/technical/workflows.md:54).
Weekly analytics fold append-only correction chains before aggregating durations or qualifying outcomes, avoiding double-counting (Scenario W14).
Tasks deferred \ge 2 times generate an advisory flag with code policy_review_required and evidence event IDs, prompting review options rather than automatic rescheduling (Scenario W10).
Every metric returns structured fields: name, numerator, denominator, unknown_count, and coverage (Scenario W12).
Tasks deferred \ge 2 times generate an advisory flag with code policy_review_required and evidence event IDs.
Running life review --period week performs ZERO writes to Radicale CalDAV and ZERO updates to task lifecycle statuses.

Notes

Every metric carries the same {name, numerator, denominator, unknown_count, coverage} shape plus its own observation interval, view, attribution and unit — no consumer has to special-case a metric.
Observed zero is distinguished from never observed by both the counts (0/5 vs 0/0) and a history_incomplete warning naming the unobserved days.
Career floor reuses #22's CareerFloor::from_day_outcomes; deferrals reuse #25's review prompt; the advisory flag is review_flag.v1 and degrades with judgment_unavailable while deterministic metrics stay put.
Unimplemented-command fixtures moved to sync in three suites and the skill's command reference was updated in the same commit.
No dependency added.

Blocked by

#029: Append-Only Timeline Fact Corrections

## Summary Implement the weekly review analytics engine (`POST /v1/reviews` and `life review --period week`), computing evidence-based metrics with explicit numerator, denominator, and unknown coverage breakdown, evaluating weekday career floor attainment based strictly on recorded qualifying outcome facts (never calendar allocations), tracking task deferral frequency, and generating advisory review flags without mutating calendar objects or task commitments. ## Background & Technical Rationale Productivity software often presents misleading analytics: 1. **Vanity Allocations vs Reality:** Counting scheduled calendar blocks as "work completed" creates a dangerous illusion of progress. A user who blocks out four hours for career writing but gets pulled into meetings or procrastinates has not achieved the outcome. 2. **Punishing Observation Gaps:** If a user starts using the system on a Wednesday, or takes an off-grid vacation without logging into the app, naive metric engines treat the unobserved days as "zero activity / failed habit," inducing guilt and corrupting historical averages. 3. **Automated Destructive Rescheduling:** In response to missed goals, automated tools frequently reschedule or delete tasks without consent. Life implements a rigorous, mathematically honest analytics model: - **Career Floor Attainment (Scenario W12):** Life defines a core personal policy default: *One meaningful career action per weekday*. Attainment requires an explicit qualifying outcome fact (`qualifies_career_floor: true` or qualifying outcome on an `area-career` task) logged for that weekday. Allocating a calendar block is NOT attainment. - **Mathematical Transparency:** Every metric must return a structured tuple: $$\{\text{name}, \text{numerator}, \text{denominator}, \text{unknown\_count}, \text{coverage}\}$$ - **Epistemic Honesty Regarding Gaps:** Days prior to service initialization or intervals without observation are reported as `unknown_count`, rather than being conflated with zero activity. Zero strictly means *observed absence* under the stated definition. - **Planned Duration vs Actual Effort:** Planned block duration (from Radicale VEVENTs) is reported separately from user-reported actual effort (from `life_events`). If actual duration was omitted in the report, it is tracked as unknown rather than guessed. - **Deferral Tracking:** Tasks deferred two or more times trigger advisory review prompts (e.g. offer smaller scope, move to someday, retain, or cancel) without automated deletion or reprioritization. - **Strictly Advisory & Read-Only:** The weekly review endpoint is an analytical read operation. It makes ZERO writes to Radicale and modifies no task states. ## Exact Technical References & Specifications ### 1. Workflows Specification (`docs/technical/workflows.md`) Section: `## Lifecycle and review` (line 37): ```markdown | Workflow | Input and reads | Decision and approval | Writes and observable result | Failure path | |---|---|---|---|---| | Weekly review | Week, timezone, live tasks/events and journal coverage; optional context/Jev | Compare intended outcomes to recorded outcomes, not allocated hours to effort | Advisory review, evidence-linked patterns and optional separately reviewed proposals | Missing history and context/Jev outages are disclosed; review does not change commitments | ``` Section: `## Personal policy defaults` (lines 44, 48, 50): ```markdown - One meaningful career action per weekday. Success requires an explicit qualifying outcome linked to the action and day; allocating a calendar block is not success. Qualification must be user-approved or satisfy a reviewed deterministic rubric, never a model's unreviewed inference. - Explicit review after two confirmed deferrals of the same item since its last review. External differences do not count as deliberate deferrals without evidence. The prompt can offer smaller scope, queue/someday, retain or cancel; it does not decide automatically. Policy exceptions are explicit, scoped and recorded with reason if supplied. No guilt-driven messaging, inferred completion, silent deletion or automatic idea promotion. Life-area categories are not diagnoses or rankings of human worth. ``` Section: `## Weekly analytics` (lines 52–56): ```markdown Return each metric's numerator, denominator, observation interval and coverage. For example, career-floor attainment is qualifying-outcome weekdays / observed eligible weekdays; days outside service history or with missing outcome observation are reported separately as unknown. Zero means observed absence under the stated definition, not absent records in an unobserved period. Report confirmed service completions separately from observed external completion differences. Count deferrals only where the event semantics establish deferral. Report planned block duration separately from user-reported actual effort; unknown actual duration is excluded with its count disclosed. Correction-aware totals identify the correction policy and retain links to original evidence. Recommendations and review flags cite inputs and question/model versions, not unsupported causal diagnoses. ``` ### 2. CLI and API Route & Payloads (`docs/technical/cli-api.md`) Section: `## Command-to-route table` (line 45): ```markdown | `life review --period week` | POST /v1/reviews | read | ``` Section: `## Command payloads and results` (lines 92, 104): ```markdown | Review | period week; optional anchor_date | metrics {name,numerator,denominator,unknown_count,coverage}, evidence IDs, advisory flags | Period week means Monday local midnight through next Monday; anchor_date selects the containing week. Agenda defaults require an explicit period; task lists have no implicit deadline cutoff. ``` Section: `## Error identifiers` (line 127): ```markdown Non-error warning identifiers: history_incomplete, policy_review_required. ``` ### 3. Verification Scenario W12 (`docs/technical/verification.md`) Section: `## Workflow scenarios` (line 26): ```markdown | ID | Requirement and specification | Input / action | Observable acceptance | |---|---|---|---| | W12 | Weekly review (workflows.md#weekly-analytics) | Planned blocks, explicit qualifying outcome, missing observation days | Career floor uses recorded outcome, not allocation; numerator/denominator/unknown coverage disclosed | ``` ## What to build ### 1. Week Interval Resolver (`src/domain/analytics/interval.rs`) - In the configured IANA timezone, determine the weekly review bounds: - Week start: Monday 00:00:00 local time. - Week end: Next Monday 00:00:00 local time (exclusive). - If `anchor_date` is supplied (e.g. `2026-09-23`), compute the Monday–Monday interval containing that date. - Identify the 5 eligible weekdays (Monday through Friday) in that local interval. ### 2. Career Floor Attainment Metric Calculator (`src/domain/analytics/career_floor.rs`) - For each of the 5 weekdays: - Determine service history coverage and outcome observation status (`docs/technical/workflows.md:54`): - Did the user report work outcomes or verify activity for this day? - If the day falls outside service history, in an observation gap, or has missing outcome observation, increment `unknown_count` and record under `unknown_days`. Missing outcome observation is NEVER punished as a failure. - If the day has valid outcome observation coverage: - Query effective corrected `work_block_outcome` facts for that date (applying folded timeline corrections from #029, per `docs/technical/timeline-consistency.md:164`): - Check if `after_json.qualifies_career_floor == true`. - Crucial Invariant: Do NOT infer qualification from `area-career` category membership alone or scheduled attendance; qualification requires explicit user assertion `qualifies_career_floor: true` or an evaluated deterministic rubric (`docs/technical/workflows.md:44`). - If a qualifying outcome fact exists, increment `numerator` and increment `denominator`. - If outcome was observed and confirmed no qualifying action occurred, do NOT increment numerator; increment `denominator`. - Resulting metric structure: ```json { "name": "weekday_career_floor_attainment", "numerator": 3, "denominator": 4, "unknown_count": 1, "coverage": { "observed_days": ["2026-09-21", "2026-09-22", "2026-09-23", "2026-09-24"], "unknown_days": ["2026-09-25"] } } ``` ### 3. Focus Duration vs Actual Effort Calculator (`src/domain/analytics/duration.rs`) - Query scheduled VEVENT work blocks in the week interval: - Sum duration of planned focus blocks: $\sum \text{planned\_minutes}$. - Query effective corrected `work_block_outcome` facts in the week interval (folding correction chains from #029): - For each effective outcome: - If `actual_minutes` is not null: add to $\sum \text{actual\_minutes}$. - If `actual_minutes` is null: increment `unknown_count`. - Return metric: ```json { "name": "focus_block_effort", "numerator": 360, "denominator": 450, "unit": "minutes", "unknown_count": 2, "coverage": {"planned_blocks": 5, "reported_blocks": 3, "unreported_blocks": 2} } ``` ### 4. Deferral Frequency & Policy Flag Engine (`src/domain/analytics/deferrals.rs`) - Query `life_events` for task update events representing deferrals (e.g. moving `planned_start` or updating strength). - Group by task `uid`: - If a task has been deferred $\ge 2$ times since its last review, generate an advisory flag: ```json { "code": "policy_review_required", "task_id": "itm_task_789", "title": "Refactor database migrations", "deferral_count": 2, "message": "Item deferred 2 times since last review; consider smaller scope, moving to someday, or cancelling", "evidence_event_ids": ["evt_def_1", "evt_def_2"] } ``` - Ensure this generates an advisory flag only: do NOT automatically reschedule, cancel, or delete the task. ### 5. Axum Handler & CLI Interface (`src/api/reviews.rs`, `src/cli/review.rs`) - Implement `POST /v1/reviews`: - Request body: ```json { "period": "week", "anchor_date": "2026-09-23" } ``` - Response (HTTP 200 OK): ```json { "schema_version": 1, "request_id": "req_rev_123", "status": "ok", "data": { "period": "week", "from": "2026-09-21T00:00:00+10:00", "to": "2026-09-28T00:00:00+10:00", "timezone": "Australia/Brisbane", "metrics": [ { "name": "weekday_career_floor_attainment", "numerator": 3, "denominator": 4, "unknown_count": 1, "coverage": { "observed_days": ["2026-09-21", "2026-09-22", "2026-09-23", "2026-09-24"], "unknown_days": ["2026-09-25"] } }, { "name": "focus_block_effort", "numerator": 360, "denominator": 450, "unit": "minutes", "unknown_count": 2, "coverage": {"planned_blocks": 5, "reported_blocks": 3, "unreported_blocks": 2} } ], "advisory_flags": [ { "code": "policy_review_required", "task_id": "itm_task_789", "deferral_count": 2, "evidence_event_ids": ["evt_def_1", "evt_def_2"] } ] }, "warnings": [ { "code": "history_incomplete", "message": "Friday 2026-09-25 was unobserved; counted in unknown_count rather than failure" } ], "error": null } ``` - CLI Command: `life review --period week [--anchor-date YYYY-MM-DD] [--json]` - Renders human-readable summary table and metric ratios, or JSON envelope. ## Acceptance Criteria - [x] Career floor metric counts only weekdays with explicit qualifying outcome facts (`qualifies_career_floor: true`), rejecting scheduled blocks without outcome reports (verifying Scenario W12). - [x] Days prior to service initialization, observation gaps, or days with missing outcome observation are counted under `unknown_count` and are NOT treated as failure days (Scenario W12, `docs/technical/workflows.md:54`). - [x] Weekly analytics fold append-only correction chains before aggregating durations or qualifying outcomes, avoiding double-counting (Scenario W14). - [x] Tasks deferred $\ge 2$ times generate an advisory flag with code `policy_review_required` and evidence event IDs, prompting review options rather than automatic rescheduling (Scenario W10). - [x] Every metric returns structured fields: `name`, `numerator`, `denominator`, `unknown_count`, and `coverage` (Scenario W12). - [x] Tasks deferred $\ge 2$ times generate an advisory flag with code `policy_review_required` and evidence event IDs. - [x] Running `life review --period week` performs ZERO writes to Radicale CalDAV and ZERO updates to task lifecycle statuses. ## Notes - Every metric carries the same `{name, numerator, denominator, unknown_count, coverage}` shape plus its own observation interval, view, attribution and unit — no consumer has to special-case a metric. - Observed zero is distinguished from never observed by both the counts (`0/5` vs `0/0`) and a `history_incomplete` warning naming the unobserved days. - Career floor reuses #22's `CareerFloor::from_day_outcomes`; deferrals reuse #25's review prompt; the advisory flag is `review_flag.v1` and degrades with `judgment_unavailable` while deterministic metrics stay put. - Unimplemented-command fixtures moved to `sync` in three suites and the skill's command reference was updated in the same commit. - No dependency added. ## Blocked by - #029: Append-Only Timeline Fact Corrections

yuris changed title from ~~Issue #030: Weekly Review Analytics & Career Floor Evaluation~~ to Weekly Review Analytics & Career Floor Evaluation

2026-09-22 20:02:34 +00:00

yuris referenced this issue

2026-09-22 23:20:16 +00:00

feat(jev): advisory question families and graceful degradation #57

yuris referenced this issue

2026-09-23 02:16:55 +00:00

feat(api): interruption fact logging and schedule replanning #69

yuris referenced this issue from a pull request that will close it,

2026-09-23 04:26:32 +00:00

feat(api): weekly review analytics and career floor evaluation #77

yuris closed this issue

2026-09-23 04:27:53 +00:00