Skip to content

[METRIC] durabilidade por token — eficiência de esforço-IA (output durável por token gasto) #90

@trentas

Description

@trentas

Follow-up do épico #65. Só faz sentido agora que a telemetria de uso (usage_rollup) existe (#68/#69).

Hipótese

Essa métrica nos ajuda a entender como IA muda software delivery porque mede se o esforço de IA virou código durável ou retrabalho — cruzando input (tokens gastos por repo/período, do usage_rollup) com output (linhas sobreviventes / estabilização do engine) no mesmo grão. É a tradução numérica da tese central do épico.

Definição

Por (repo, período): durabilidade_por_token = (linhas AI-origin sobreviventes) / (output_tokens do agente naquele repo/período), normalizado por mil/milhão de tokens. Variante simples: estabilização_AI / Mtoken. Unidades explícitas; janela = a mesma lookback do dashboard. Edge cases: repos sem telemetria (N/A), divisão por zero (sem tokens → sem métrica), defasagem temporal entre análise de durabilidade (latest run) e o período de uso.

Fonte do sinal

múltiplas fontes

Risco de ranqueamento individual

Grão é (repo, período) vindo do usage_rollup, que não tem dimensão de pessoa. Mitigação reusa a supressão k-anonimato do #69 (só renderiza com ≥N contribuidores; abaixo cai em "outros"). Nenhuma tela por dev — Princípio #2 preservado por construção.

Chain checklist (releasa completa)

  • analysis module (iris/analysis/) — ou compute na plataforma, já que o input vive no usage_rollup (decidir onde mora o cálculo)
  • aggregator (iris/metrics/aggregator.py) — se calculado no engine
  • python schema (iris/models/metrics.py) — se aplicável
  • report writer (iris/reports/writer.py)
  • narrative findings (iris/reports/narrative.py) — se threshold aplicável
  • TS types (platform/src/types/)
  • platform UI — provável extensão da seção AI Agent Usage ([FEAT] Exposição: views de uso por repo/time com supressão k-anonimato + cruzamento com durabilidade #69)
  • docs/METRICS.md atualizado

Notas / prior art

Decisão de design pendente: o cálculo cruza telemetria (plataforma) com durabilidade (engine/payload). Como o usage_rollup só existe na plataforma, o cruzamento provavelmente mora na camada de query da plataforma (estendendo computeAgentUsage), não no engine Python. Confirmar antes de implementar.

Metadata

Metadata

Assignees

No one assigned

    Labels

    type: metricNova métrica ou alteração de métrica existente

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions