mickyarun
diff --git a/‎backend/alembic/versions/a9a073feecb7_velocity_aggregates_rollup.py‎
Lines changed: 106 additions & 0 deletions b/‎backend/alembic/versions/a9a073feecb7_velocity_aggregates_rollup.py‎
Lines changed: 106 additions & 0 deletions
diff --git a/‎backend/alembic/versions/af5af83d4327_feature_learnings_metrics_column.py‎
Lines changed: 34 additions & 0 deletions b/‎backend/alembic/versions/af5af83d4327_feature_learnings_metrics_column.py‎
Lines changed: 34 additions & 0 deletions
diff --git a/‎backend/app/agents/prompts/__init__.py‎
Lines changed: 22 additions & 0 deletions b/‎backend/app/agents/prompts/__init__.py‎
Lines changed: 22 additions & 0 deletions
diff --git a/‎backend/app/agents/prompts/learning_prompt.py‎
Lines changed: 155 additions & 0 deletions b/‎backend/app/agents/prompts/learning_prompt.py‎
Lines changed: 155 additions & 0 deletions
diff --git a/‎backend/app/agents/skill_mapping.py‎
Lines changed: 1 addition & 0 deletions b/‎backend/app/agents/skill_mapping.py‎
Lines changed: 1 addition & 0 deletions
@@ -0,0 +1,106 @@
+"""velocity_aggregates_rollup
+
+Revision ID: a9a073feecb7
+Revises: af5af83d4327
+Create Date: 2026-05-30 21:54:26.636330
+
+"""
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = 'a9a073feecb7'
+down_revision: str | None = 'af5af83d4327'
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    # The ``bud_status`` enum already exists in the DB (created by an
+    # earlier migration). Use postgresql.ENUM with create_type=False so
+    # we reuse the existing type rather than re-CREATE-ing it — per the
+    # alembic_enum_create_table gotcha documented in project memory.
+    bud_status = postgresql.ENUM(name='bud_status', create_type=False)
+    jsonb_empty_list = sa.text("'[]'::jsonb")
+    now_sql = sa.text('now()')
+    op.create_table(
+        'velocity_aggregates',
+        sa.Column('org_id', sa.UUID(), nullable=False),
+        sa.Column('complexity', sa.Integer(), nullable=False),
+        sa.Column('phase', bud_status, nullable=False),
+        sa.Column('n_samples', sa.Integer(), server_default='0', nullable=False),
+        sa.Column(
+            'sample_window',
+            postgresql.JSONB(astext_type=sa.Text()),
+            server_default=jsonb_empty_list,
+            nullable=False,
+        ),
+        sa.Column(
+            'contributing_bud_ids',
+            postgresql.JSONB(astext_type=sa.Text()),
+            server_default=jsonb_empty_list,
+            nullable=False,
+        ),
+        sa.Column('p50_days', sa.Numeric(precision=8, scale=2), nullable=True),
+        sa.Column('p70_days', sa.Numeric(precision=8, scale=2), nullable=True),
+        sa.Column('p85_days', sa.Numeric(precision=8, scale=2), nullable=True),
+        sa.Column('pert_optimistic', sa.Numeric(precision=8, scale=2), nullable=True),
+        sa.Column('pert_most_likely', sa.Numeric(precision=8, scale=2), nullable=True),
+        sa.Column('pert_pessimistic', sa.Numeric(precision=8, scale=2), nullable=True),
+        sa.Column(
+            'running_mean',
+            sa.Numeric(precision=10, scale=4),
+            server_default='0',
+            nullable=False,
+        ),
+        sa.Column(
+            'running_m2',
+            sa.Numeric(precision=12, scale=4),
+            server_default='0',
+            nullable=False,
+        ),
+        sa.Column('running_mean_30d_ago', sa.Numeric(precision=10, scale=4), nullable=True),
+        sa.Column('snapshot_taken_at', sa.DateTime(timezone=True), nullable=True),
+        sa.Column('id', sa.UUID(), nullable=False),
+        sa.Column(
+            'created_at',
+            sa.DateTime(timezone=True),
+            server_default=now_sql,
+            nullable=False,
+        ),
+        sa.Column(
+            'updated_at',
+            sa.DateTime(timezone=True),
+            server_default=now_sql,
+            nullable=False,
+        ),
+        sa.ForeignKeyConstraint(['org_id'], ['organizations.id']),
+        sa.PrimaryKeyConstraint('id'),
+        sa.UniqueConstraint('org_id', 'complexity', 'phase', name='uq_velocity_agg_bucket'),
+    )
+    op.create_index(
+        'ix_velocity_agg_lookup',
+        'velocity_aggregates',
+        ['org_id', 'complexity'],
+        unique=False,
+    )
+    op.create_index(
+        op.f('ix_velocity_aggregates_org_id'),
+        'velocity_aggregates',
+        ['org_id'],
+        unique=False,
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index(op.f('ix_velocity_aggregates_org_id'), table_name='velocity_aggregates')
+    op.drop_index('ix_velocity_agg_lookup', table_name='velocity_aggregates')
+    op.drop_table('velocity_aggregates')
+    # ### end Alembic commands ###
@@ -0,0 +1,34 @@
+"""feature_learnings_metrics_column
+
+Revision ID: af5af83d4327
+Revises: 0adad4d4dd8d
+Create Date: 2026-05-30 21:39:11.914718
+
+"""
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = 'af5af83d4327'
+down_revision: str | None = '0adad4d4dd8d'
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column(
+        'feature_learnings',
+        sa.Column('metrics', postgresql.JSONB(astext_type=sa.Text()), nullable=True),
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_column('feature_learnings', 'metrics')
+    # ### end Alembic commands ###
@@ -0,0 +1,22 @@
+# Copyright 2025-2026 Arun Rajkumar
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Prompt builders for stage-specific agents that don't fit the legacy
+``app.services.agent_prompts`` module's section-writing pattern.
+
+The Learning Agent lives here rather than in ``agent_prompts`` because
+its output (a retrospective recap) is not a BUD-document section the
+existing builders manipulate — it consumes structured metrics and
+writes to ``feature_learnings.retrospective_md`` instead.
+"""
@@ -0,0 +1,155 @@
+# Copyright 2025-2026 Arun Rajkumar
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Prompt builder for the post-close Learning Agent.
+
+The recap is grounded entirely on data the prompt builder pre-fetches
+and inlines as JSON inside the prompt body — there is no MCP read tool
+for these metrics. Rationale: the agent reads, never writes, and the
+data is in scope at prompt-build time. An MCP tool would only add
+round-trip latency and an extra serialization contract to maintain.
+
+Cross-BUD context: the builder pulls the top-N (default 3) most
+semantically similar prior retrospectives via cosine over
+``feature_learnings.embedding`` and injects them as few-shot examples
+so the recap can call out trends (e.g. "the design phase has dragged
+on the last 3 similar BUDs").
+"""
+
+import json
+import uuid
+from typing import Any
+
+import structlog
+
+from app.models.bud import BUDDocument
+from app.repositories.feature_learning import FeatureLearningRepository
+from app.services.embedding_service import embedding_service
+from app.services.skill_loader import Skill
+
+logger = structlog.get_logger(__name__)
+
+PRIOR_RECAP_LIMIT = 3
+PRIOR_RECAP_SNIPPET_CHARS = 1_500
+
+
+def _summarize_bud_for_embedding(bud: BUDDocument) -> str:
+    """Concatenate the BUD's identity + brief into a single embedding input."""
+    parts = [
+        bud.title or "",
+        (bud.requirements_md or "")[:1_500],
+    ]
+    return "\n\n".join(p for p in parts if p)
+
+
+async def _fetch_prior_recaps(
+    db: Any,
+    org_id: uuid.UUID,
+    bud: BUDDocument,
+) -> list[dict[str, str]]:
+    """Top-3 prior retrospectives most semantically similar to this BUD.
+
+    Embeds the current BUD's title + requirements (NOT the new metrics
+    JSON) so the similarity hits are about the work itself, not about
+    the numerical shape. Returns an empty list when the BUD's content
+    can't be embedded — the prompt builder is resilient to this.
+    """
+    try:
+        embedding = await embedding_service.embed(_summarize_bud_for_embedding(bud))
+    except Exception:
+        logger.warning("learning_prompt_embed_failed", bud_id=str(bud.id))
+        return []
+
+    repo = FeatureLearningRepository(db, org_id=org_id)
+    similar = await repo.find_similar(
+        embedding,
+        limit=PRIOR_RECAP_LIMIT,
+        exclude_bud_id=bud.id,
+    )
+    out: list[dict[str, str]] = []
+    for row in similar:
+        if not row.retrospective_md:
+            continue
+        out.append(
+            {
+                "bud_id": str(row.bud_id),
+                "retrospective_md": row.retrospective_md[:PRIOR_RECAP_SNIPPET_CHARS],
+            }
+        )
+    return out
+
+
+def _format_prompt_body(
+    skill: Skill,
+    bud: BUDDocument,
+    metrics: dict[str, Any],
+    prior_recaps: list[dict[str, str]],
+) -> str:
+    """Assemble the skill body, BUD identity, structured metrics, and prior recaps."""
+    prior_block = (
+        json.dumps(prior_recaps, indent=2)
+        if prior_recaps
+        else "(no prior retrospectives available — write the first one for this complexity bucket)"
+    )
+    return (
+        f"{skill.prompt}\n\n"
+        f"## BUD\n"
+        f"Number: BUD-{bud.bud_number:03d}\n"
+        f"Title: {bud.title}\n\n"
+        f"## Original PRD (excerpt)\n"
+        f"{(bud.requirements_md or '')[:2_000]}\n\n"
+        f"## Structured metrics for this BUD\n"
+        f"```json\n{json.dumps(metrics, indent=2, default=str)}\n```\n\n"
+        f"## Prior retrospectives from similar BUDs (most-similar first)\n"
+        f"{prior_block}\n\n"
+        f"## Task\n"
+        f"Write the retrospective markdown for this BUD. The output is read by\n"
+        f"the team on the BUD detail Learnings tab and used as cross-BUD\n"
+        f"context for future recaps. Follow the skill's workflow exactly.\n"
+    )
+
+
+async def build_learning_prompt(
+    bud: BUDDocument,
+    skill: Skill,
+    org_id: uuid.UUID,
+    db: Any,
+) -> tuple[str, str | None]:
+    """Build the prompt for the post-close Learning Agent.
+
+    Pulls the freshly-persisted ``FeatureLearning.metrics`` envelope
+    from the DB (written seconds earlier by
+    ``bud_metrics.compute_and_persist``) and injects it inline, then
+    appends up to three vector-similar prior recaps for trend grounding.
+    Returns ``(prompt, working_dir=None)`` — the agent doesn't run
+    against a repo working directory.
+    """
+    repo = FeatureLearningRepository(db, org_id=org_id)
+    learning = await repo.get_for_bud(bud.id)
+    if learning is None or not learning.metrics:
+        logger.warning(
+            "learning_prompt_no_metrics_envelope",
+            bud_id=str(bud.id),
+            bud_number=bud.bud_number,
+        )
+        # Defensive: build a usable prompt anyway so the agent doesn't
+        # silently degrade into "(no data)" output — a missing envelope
+        # is a bug we want surfaced as a written recap that flags it.
+        metrics: dict[str, Any] = {"_warning": "metrics envelope missing"}
+    else:
+        metrics = dict(learning.metrics)
+
+    prior_recaps = await _fetch_prior_recaps(db, org_id, bud)
+    prompt = _format_prompt_body(skill, bud, metrics, prior_recaps)
+    return prompt, None
@@ -77,6 +77,7 @@ def get_skill_for_agent(agent_name: str) -> str | None:
     BUDStatus.DESIGN: AgentType.DESIGN,
     BUDStatus.TECH_ARCH: AgentType.TECH_PLAN,
     BUDStatus.TESTING: AgentType.TEST_PLAN,
+    BUDStatus.CLOSED: AgentType.LEARNING,
 }
 
 # Maps a BUD section key to the agent type that handles chat for that
Original file line number	Diff line number	Diff line change
`@@ -77,6 +77,7 @@ def get_skill_for_agent(agent_name: str) -> str \| None:`
`77`	`77`	`BUDStatus.DESIGN: AgentType.DESIGN,`
`78`	`78`	`BUDStatus.TECH_ARCH: AgentType.TECH_PLAN,`
`79`	`79`	`BUDStatus.TESTING: AgentType.TEST_PLAN,`
	`80`	`+ BUDStatus.CLOSED: AgentType.LEARNING,`
`80`	`81`	`}`
`81`	`82`
`82`	`83`	`# Maps a BUD section key to the agent type that handles chat for that`