360 Feedback Pipeline — Engineering Guide

Install

cd workbench/feedback-360
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
git submodule update --init --recursive

Requires Python 3.10+ and pdfplumber (see requirements.txt). No network access is needed at runtime.

Forge + Kitchen Sink submodules

blueprints/ and kitchensink/ are git submodules. After clone:

git submodule update --init --recursive
bash blueprints/sdlc/methodologies/forge/setup/sync-forge-cursor-rules.sh sync --preset recommended
./scripts/sync-capablio-ks-static.sh   # copy KS CSS into forge360/ui/static/ks/

See forge/forge.config.yaml and docs/capablio-ks-token-map.md.

Enterprise uplift (PDCA)

Cursor prompt pack and CLI harness:

./scripts/capablio-uplift/pdca-run-phase.sh 00 plan
./scripts/capablio-uplift/pdca-check.sh 02A

• Prompts: docs/prompts/capablio-enterprise-uplift/
• Dual wiki: wiki/external/, wiki/internal/, wiki/shared/
• Agent rules: AGENTS.md, .cursor/rules/000-capablio-*.mdc

.venv/bin/python -m feedback360 \
  --thomas sources/thomas-360-report.pdf \
  --snapshot sources/snapshot-deck.pdf \
  --out report \
  --stage all

Flags

Stages

1. parse — Reads --thomas (and optional --snapshot), writes <out>/data.json.
2. analyze — Reads <out>/data.json, writes <out>/metrics.json.
3. render — Reads both JSON files, writes <out>/360-report.html and <out>/wiki/*.html.
4. all — Runs parse → analyze → render in order.

Dynamic mode (--serve)

After the pipeline has produced JSON artifacts, start the live-controls server:

.venv/bin/python -m feedback360 --serve --out report --port 8913

Open http://127.0.0.1:8913/ for the dynamic dashboard. The static offline report remains at report/360-report.html.

POST /api/metrics body (all keys optional; unknown keys ignored):

{
  "w_importance": 0.5,
  "w_performance": 0.35,
  "w_blindspot": 0.15,
  "exec_relevance": {"PROVIDES VISION & DIRECTION": 1.5},
  "rater_weights": {"Manager": 1.0, "Peer": 1.0, "Team": 1.0, "Customer": 1.0},
  "importance_source": "avg"
}

Defaults match metrics.json weights plus uniform rater weights and importance_source: "avg". Partial exec_relevance merges over the built-in executive-relevance table. Invalid importance_source values return HTTP 400 with {"error": "..."}. The response echoes effective params under "params" and is deterministic for identical inputs.

Qualitative analytics

The analyze stage adds three deterministic sections to metrics.json:

• sentiment — Lexicon-based tone scoring per comment (−1 to +1), aggregated by question and theme.
• swot — Keyword-rule extraction into strengths, weaknesses, opportunities, and threats with quantitative corroboration.
• section_summaries — Template-built executive summaries for each report tab (recomputed via /api/metrics when weights change).

No ML models or network access; see pipeline.md for method details.

Each stage exits non-zero with a clear message if validation fails or prerequisite files are missing.

Output inventory

The Development Plan interview is documented in pdp.md. It runs only in 360 Insights Studio (--app or the desktop shell); pipeline stages never create these files.

Rerunning on future report editions

1. Place new PDFs under sources/ (do not commit confidential exports unless policy allows).
2. Run the full pipeline with updated --thomas / --snapshot paths.
3. Compare data.json diff — schema version 1 should remain stable; counts (12 competencies, 54 statements) are validated during parse.
4. If geometric extraction fails for specific statements, check warnings in data.json and add targeted fixes to overrides.json (see below).
5. Open report/360-report.html locally; use report/wiki/ for interpretation help.

overrides.json mechanism

Optional file at the project root. Same nesting as data.json. When the parser cannot reliably extract a value, merge overrides as a last resort:

{
  "competencies": [
    {
      "name": "EXAMPLE",
      "statements": [
        {"text": "…", "avg_excluding_self": 5.0}
      ]
    }
  ]
}

Each applied JSON path is recorded in data.json → overrides_applied. Prefer fixing parse_360.py when the PDF layout is systematically parseable.

forge360 platform

Multi-user 360 survey service (FastAPI) beside the offline pipeline:

• forge360 overview — architecture, configuration, how to run, tests.
• forge360 API reference — every /api/* route, auth, and roles.
• forge360 cryptography — envelope v1/v2, key registry, reseal, zero-knowledge audit.
• forge360 lifecycle — survey status machine, role matrix, wrap-up and PDP journey.

See feature-status.md for the PLN-* implementation flags.

Adaptive Feedback Framework

Production-scale Capablio architecture pack (question families, cooldown, assembly engine, PDP recurrence, tenant overlays, pricing):

• Framework hub
• AFF implementation status (AFF-* Unimplemented / Partial)
• User guide — subjects and raters

Related docs

• User guide — Capablio subjects and raters (no jargon).
• Operator guide — facilitator-facing install, daily workflow, and troubleshooting (no jargon).
• Engineering map — one-page architecture: pipeline, Studio API, desktop, packaging, PDCA.
• Feature status — implemented capability flag matrix (offline pipeline, Studio, forge360).
• Survey platform vision — product spec for forge360 (now implemented): roles, encryption, lifecycle.
• forge360 Google Sign-In (GCP) — OAuth Web client setup, env vars, and ID-token auth flow for the forge360 FastAPI package.
• Studio app logic — state machines, gates, and invariants behind the Studio API; pairs with the generated reader page wiki/studio.html.
• Studio HTTP API — workspaces, background generate jobs, verify-gated export (--app, port 8914).
• Desktop shell — Electron lifecycle, IPC, spawn/attach, screen map.
• Packaging — PyInstaller backend, electron-builder installers, CI matrix, unsigned-app caveats.
• AI providers — optional narrative enrichment; in-memory API keys.
• Personal Development Plan — guided interview, validation rules, and pdp.json schema.
• Data contract — data.json and metrics.json field reference.
• Pipeline architecture — parse/analyze/render design, verification harness, PDCA orchestration.
• PDCA log — iteration history from orchestration/logs/pdca/.