Connect Review

When to invoke

Use when: "review the contact flow", "review this Connect solution", "is the Lex bot well designed", "why is the voice bot slow", "review the IVR", "check the phone assistant before go-live".

Preamble

eval "$(~/.vibestack/bin/vibe-slug 2>/dev/null)" 2>/dev/null || SLUG="unknown"
_LEARN_FILE="${VIBESTACK_HOME:-$HOME/.vibestack}/projects/${SLUG:-unknown}/learnings.jsonl"
if [ -f "$_LEARN_FILE" ]; then
  _LEARN_COUNT=$(wc -l < "$_LEARN_FILE" 2>/dev/null | tr -d ' ')
  echo "LEARNINGS: $_LEARN_COUNT entries loaded"
  if [ "$_LEARN_COUNT" -gt 5 ] 2>/dev/null; then
    ~/.vibestack/bin/vibe-learnings-search --limit 5 2>/dev/null || true
  fi
else
  echo "LEARNINGS: none yet"
fi

{{include lib/snippets/session-host.md}}

{{include lib/snippets/decision-brief.md}}

{{include lib/snippets/working-protocols.md}}

{{include lib/snippets/state-protocols.md}}

User-invocable

When the user types /connect-review, run this skill.

Step 0: Find the inputs

Locate the five inputs in the repo before reviewing anything. Use Glob and Grep; do not guess from file names alone.

grep -rlE '"Version": *"2019-10-30"' --include='*.json' . 2>/dev/null | head
grep -rlE 'aws_connect_|aws_lexv2models_|CfnContactFlow|CfnBot' --include='*.tf' --include='*.ts' --include='*.py' . 2>/dev/null | head
grep -rlE 'converse\(|invoke_model\(|InvokeModelCommand|ConverseCommand|bedrock-runtime' . 2>/dev/null | grep -vE 'node_modules|\.venv' | head
grep -rlE 'sampleUtterances|"intentName"' --include='*.json' . 2>/dev/null | head

If an input is missing, ask the user for the path or the resource id. If the aws CLI is configured, fill gaps with read-only calls and record the region — it decides whether the German-market notes apply:

aws sts get-caller-identity --query Account --output text
aws configure get region
aws connect list-instances --query 'InstanceSummaryList[].[Id,InstanceAlias]' --output table
aws connect list-contact-flows --instance-id "$INSTANCE_ID" --output table
aws connect describe-contact-flow --instance-id "$INSTANCE_ID" --contact-flow-id "$FLOW_ID" --query 'ContactFlow.Content' --output text > "${TMPDIR:-/tmp}/connect-review-flow.json"
aws lexv2-models list-bots --output table
aws lexv2-models describe-bot --bot-id "$BOT_ID"
aws lexv2-models list-intents --bot-id "$BOT_ID" --bot-version DRAFT --locale-id de_DE
aws lambda get-function-configuration --function-name "$FN" --query '[Timeout,MemorySize,Runtime]'

Only describe, list, get and filter-log-events calls are allowed. Never call update-*, create-*, build-bot-locale or put-*.

Write down the solution shape in one paragraph before continuing: entry number → flow → Lex bot → Lambda → Bedrock → back, plus which locale, which model and which region. This becomes the "Solution summary" in the report.

Step 1: Flow structure

Walk every flow from StartAction following Transitions.NextAction, Transitions.Conditions[].NextAction and Transitions.Errors[].NextAction. Build the graph before judging it — a block that looks unreachable in the JSON often is.

Evidence for a flow finding is the flow name plus the block Identifier (or Terraform resource address and line).

# Overrides live on the hours-of-operation resource, not in the flow. An empty
# override list only means something if the call succeeded — otherwise N-A.
if hoo=$(aws connect describe-hours-of-operation \
      --instance-id "$INSTANCE_ID" --hours-of-operation-id "$HOO_ID" \
      --query 'HoursOfOperation.[Name,TimeZone,ParentHoursOfOperations[].Id]' \
      --output json 2>/dev/null); then
  printf '%s\n' "$hoo"
  aws connect list-hours-of-operation-overrides \
    --instance-id "$INSTANCE_ID" --hours-of-operation-id "$HOO_ID" \
    --query 'HoursOfOperationOverrideList[].[Name,OverrideType,EffectiveFrom,EffectiveTill]' \
    --output json 2>/dev/null \
    || echo "OVERRIDES: N-A (list call failed for $HOO_ID)"
else
  echo "HOURS: N-A (describe failed — no access, or wrong instance/hours id)"
fi
# Repeat both calls for every id in ParentHoursOfOperations: a child inherits the
# parent's overrides, and they are not in the child's own list.

Step 2: Lex bot design

Read every Intent.json and Slot.json in each locale, or the equivalent IaC resources.

# An utterance is a collision only when two DIFFERENT intents in the SAME locale
# share it. Keep locale and intent from the export path
# (BotLocales/<locale>/Intents/<intent>/Intent.json) and normalise the text
# before comparing — dropping the filenames turns repeats inside one intent, and
# the same utterance in two locales, into false collisions. grep exits 1 for
# "no matches" and above 1 for a real failure; tell them apart instead of
# reading an empty result as "no duplicates". Case folding is ASCII only, so a
# capitalised umlaut is compared as written.
BOT_ROOT="${BOT_ROOT:-BotLocales}"
raw=$(grep -rHoE '"utterance"[[:space:]]*:[[:space:]]*"[^"]*"' \
        --include='Intent.json' "$BOT_ROOT" 2>/dev/null)
st=$?
if [ "$st" -gt 1 ]; then
  echo "UTTERANCES: N-A (scan failed, grep status $st)"
elif [ "$st" -eq 1 ]; then
  echo "UTTERANCES: N-A (no sample utterances found under $BOT_ROOT)"
else
  printf '%s\n' "$raw" | awk '
    {
      if (match($0, /BotLocales\/[^\/]+\/Intents\/[^\/]+\/Intent\.json:/) == 0) { skipped++; next }
      path = substr($0, RSTART, RLENGTH - 1)
      rest = substr($0, RSTART + RLENGTH)
      split(path, p, "/")
      if (match(rest, /"[^"]*"$/) == 0) next
      u = tolower(substr(rest, RSTART + 1, RLENGTH - 2))
      gsub(/[[:punct:]]/, " ", u)
      gsub(/[[:space:]]+/, " ", u)
      sub(/^ /, "", u); sub(/ $/, "", u)
      if (u == "") next
      k = p[2] SUBSEP u
      if (!(k in ints)) ints[k] = p[4]
      else if (index("," ints[k] ",", "," p[4] ",") == 0) ints[k] = ints[k] "," p[4]
    }
    END {
      for (k in ints) if (index(ints[k], ",")) {
        split(k, q, SUBSEP)
        print "COLLISION  locale=" q[1] "  intents=" ints[k] "  utterance=" q[2]
      }
      if (skipped) print "UTTERANCES: " skipped " line(s) N-A — path is not BotLocales/<locale>/Intents/<intent>/Intent.json"
    }'
fi

Step 3: Bedrock / LLM turn

Read the Lambda that calls Bedrock end to end. Trace the input from the Lex event to the model call and the output from the model to the spoken message.

grep -nE 'read_timeout|connect_timeout|requestTimeout|retries' "$LAMBDA_FILE"
grep -nE 'region_name|AWS_REGION|inferenceProfile|modelId|model_id' "$LAMBDA_FILE"
grep -nE 'system=|"system"|systemPrompt|SYSTEM_PROMPT' "$LAMBDA_FILE"

Step 4: Latency budget

Callers perceive a gap of more than about 800 ms after they stop talking as the bot not understanding them. Build the budget for the slowest turn (usually the Bedrock turn).

# A REPORT line carries Duration, Billed Duration and Init Duration (and Restore
# Duration under SnapStart). Strip the qualified ones first — only wall-clock
# Duration belongs in the latency budget. Init Duration is the cold-start
# number for the latency table — it comes out of a second pass below.
# Capture the aws status: an empty pipeline here means "no access" as often as
# it means "no invocations", and those are not the same answer.
if ! raw=$(aws logs filter-log-events --log-group-name "/aws/lambda/$FN" \
      --filter-pattern "REPORT" --start-time "$(( $(date +%s) - 86400 ))000" \
      --query 'events[].message' --output text 2>/dev/null); then
  echo "LATENCY: N-A (filter-log-events failed — no access, or no such log group)"
else
  printf '%s\n' "$raw" \
    | sed -E 's/(Billed|Init|Restore) Duration: [0-9.]+ ms//g' \
    | grep -oE 'Duration: [0-9.]+ ms' | awk '{print $2}' | sort -n \
    | awk 'function q(a, n, p,   i) { i = int(n * p); if (i < n * p) i++; if (i < 1) i = 1; if (i > n) i = n; return a[i] }
           { a[NR] = $1 }
           END { if (NR) printf "handler p50=%s p95=%s n=%d\n", q(a, NR, 0.5), q(a, NR, 0.95), NR;
                 else print "LATENCY: N-A (no REPORT lines in the window)" }'
  # Second pass for the cold-start row. The aws call already succeeded, so an
  # absence of Init Duration lines means no cold start was sampled, not no
  # access — which is a different answer from the N-A above.
  printf '%s\n' "$raw" \
    | grep -oE 'Init Duration: [0-9.]+ ms' | awk '{print $3}' | sort -n \
    | awk 'function q(a, n, p,   i) { i = int(n * p); if (i < n * p) i++; if (i < 1) i = 1; if (i > n) i = n; return a[i] }
           { a[NR] = $1 }
           END { if (NR) printf "init p50=%s p95=%s n=%d\n", q(a, NR, 0.5), q(a, NR, 0.95), NR;
                 else print "INIT: no cold start in the sampled window — leave the init row out, or mark it estimated" }'
fi

The percentile is nearest-rank: index ceil(n × p), clamped to the array. Adding one to the floor overshoots by a place whenever n × p is already a whole number.

Estimate any stage you cannot measure and mark it as an estimate. Typical ranges: Lex ASR 300–600 ms after end of speech; Lambda cold start 200 ms–3 s by runtime; Bedrock first token 400–1500 ms and full answer proportional to output tokens; Polly neural TTS 200–400 ms for one sentence. Sum them in the latency table in the report — but never add an estimated model time on top of a measured handler Duration, which already contains it. Init Duration is its own row, for the cold-start case only.

Step 5: State and idempotency

# TTL is spelled differently per tool: a `ttl` block in Terraform,
# TimeToLiveSpecification in CloudFormation, timeToLiveAttribute (TS) or
# time_to_live_attribute (Python) in CDK. A hit is not proof — read the match
# and confirm it is enabled and names a real attribute.
ttl=$(grep -rnE '(^|[^[:alnum:]_])ttl[[:space:]]*\{|TimeToLiveSpecification|timeToLiveAttribute|time_to_live|ttl_enabled' \
  --include='*.tf' --include='*.yml' --include='*.yaml' --include='*.ts' --include='*.py' . 2>/dev/null)
st=$?
if [ "$st" -gt 1 ]; then
  echo "TTL: N-A (scan failed, grep status $st)"
elif [ "$st" -eq 1 ]; then
  echo "TTL: no declaration in the scanned files — a finding only if the table is defined here; otherwise N-A"
else
  printf '%s\n' "$ttl"
fi
grep -nE 'ConditionExpression|attribute_not_exists|idempotency' "$LAMBDA_FILE"

Step 6: Observability

# An empty AlarmActions list is the case being hunted, so project the list
# itself. Keep --output json: the table formatter cannot render a list cell.
if ! aws cloudwatch describe-alarms \
      --query 'MetricAlarms[].{Alarm:AlarmName,Namespace:Namespace,Metric:MetricName,ActionsEnabled:ActionsEnabled,AlarmActions:AlarmActions}' \
      --output json 2>/dev/null; then
  echo "ALARMS: N-A (describe-alarms failed — no access)"
fi
grep -nE 'ContactId|contactId|sessionId|correlation' "$LAMBDA_FILE"

German-market note (eu-* regions): transcripts and conversation logs are personal data under the DSGVO. Report where transcripts land, the S3 lifecycle rule that deletes them, and whether the retention period is documented. Missing lifecycle rule → HIGH.

Step 7: Cost per contact

Do not hardcode prices. Every line of the formula needs its own rate, fetched one component at a time. get-products without --filters returns whatever products happen to match the service code, and truncating that JSON with head leaves a fragment of unrelated products rather than a rate — an estimate built on it would be invented. The Price List API is served from us-east-1, eu-central-1 and ap-south-1 regardless of where the workload runs: --region picks the endpoint, the regionCode filter picks the priced region.

# What each service can be filtered on. Do this before writing any filter — a
# guessed field or value returns an empty set that reads like a zero rate.
# The authoritative service-code list is:
#   aws pricing describe-services --region us-east-1 --query 'Services[].ServiceCode'
for svc in AmazonConnect AmazonLex AmazonBedrock AWSLambda AmazonPolly AmazonDynamoDB; do
  if attrs=$(aws pricing describe-services --region us-east-1 --service-code "$svc" \
        --query 'Services[0].AttributeNames' --output text 2>/dev/null); then
    printf '%s: %s\n' "$svc" "$attrs"
  else
    printf '%s: N-A (describe-services failed — no access, or wrong service code)\n' "$svc"
  fi
done

# Values that actually exist for one attribute, so the TERM_MATCH filter matches.
aws pricing get-attribute-values --region us-east-1 \
  --service-code AmazonConnect --attribute-name usagetype --max-results 100 \
  --query 'AttributeValues[].Value' --output text 2>/dev/null \
  || echo "ATTRIBUTES: N-A (get-attribute-values failed for AmazonConnect/usagetype)"

# One filtered query per formula line. Repeat with the service code, region and
# usage type for each component; keep --output json and do not truncate it.
aws pricing get-products --region us-east-1 --service-code "$SVC" \
  --filters "Type=TERM_MATCH,Field=regionCode,Value=$WORKLOAD_REGION" \
            "Type=TERM_MATCH,Field=usagetype,Value=$USAGE_TYPE" \
  --max-results 10 --output json 2>/dev/null \
  || echo "PRICING: N-A (get-products failed for $SVC/$USAGE_TYPE)"

Telephony is priced per country, number type and direction, and negotiated rates are common, so ask the user for the per-minute rate on the numbers actually in use rather than deriving one.

cost_per_call =
    call_minutes           x (connect_service_rate + telephony_rate_per_minute)
  + lex_speech_requests    x lex_speech_rate
  + lex_text_requests      x lex_text_rate
  + bedrock_input_tokens   x input_token_rate
  + bedrock_output_tokens  x output_token_rate
  + lambda_invocations     x lambda_request_rate
  + lambda_gb_seconds      x lambda_duration_rate
  + call_minutes           x contact_lens_rate            (if enabled)
  + tts_characters         x polly_neural_rate            (if neural voices are used)
  + dynamodb_writes        x write_request_rate

Fill a rate only from a query that returned one. Mark every other rate "user input", and then report the total as an order of magnitude rather than a price — say which lines are missing. What the user has to supply:

• inbound per-minute telephony rate for the country and number type in use
• the model id, and its input and output token rates
• average call length and Lex turns per call, from a real call sample
• Lambda memory, and the measured duration from Step 4
• whether Contact Lens, neural voices and any analytics add-on are enabled

Estimate the per-call quantities from a representative call: count Lex turns from the flow, tokens from the prompt size plus a typical answer, Lambda GB-seconds from memory × measured duration. Show the assumptions next to each number. Then name the largest line item and the one change that would cut it.

Output

CONNECT REVIEW
==============

Solution summary
  <one paragraph: entry point, flows, bot and locale, Lambdas, model and region, session store>
  Region: <region>  (DSGVO notes: yes/no)

Findings
| #  | Severity | Area        | Evidence                                   | Fix |
|----|----------|-------------|--------------------------------------------|-----|
| 1  | CRITICAL | Flow        | main-inbound.json block 3f2a (UpdateContactAttributes) | Remove `apiKey` from attributes; read it from Secrets Manager inside the Lambda |
| 2  | HIGH     | Latency     | handler.py:41 read_timeout unset           | Config(read_timeout=4, connect_timeout=1, retries={"max_attempts": 1}) |
| 3  | MEDIUM   | Lex         | BotLocales/de_DE/Intents/Cancel/Intent.json | Add two distinct retry prompts, maxRetries 2 |

Latency budget (slowest turn)
| Stage                           | Measured / Estimated | ms    |
|---------------------------------|----------------------|-------|
| Lex ASR end-of-speech           | estimated            | 500   |
| Lambda init (cold start)        | measured p95         | 1800  |
| Lambda handler incl. model call | measured p95         | 2100  |
| TTS                             | estimated            | 300   |
| Total                           |                      | 4700  |
| Budget                          |                      | 800   |

  Filler prompt: <none / startResponse at 400 ms>

Cost per call (assumptions in brackets)
  <one line per formula item: quantity x rate = amount, each rate marked fetched or user input>
  Total: <amount>  — order of magnitude if any rate is user input
  Largest item: <name> — <one change that cuts it>

What to test next
  1. <call scenario that exercises the worst finding, e.g. say nothing for 10 s at the main menu>
  2. <call scenario for the fallback path, e.g. ask an off-topic question twice>
  3. <call scenario for latency, e.g. ask the longest knowledge question at 09:00 after a cold night>

Not checked
  <check> — <why: no CLI access, input missing, value only resolved at runtime>

The handler row already contains the model call. Never add a separately estimated model time to a measured handler duration.

Severity meaning: CRITICAL — caller data or credentials exposed, or callers dropped; HIGH — a real call fails or the caller gives up; MEDIUM — degrades quality or costs money at scale; LOW — hygiene; N-A — the check could not run, which is reported as N-A and never as a pass or a fail.

If the user asks for a file, write the report to docs/connect-review-<YYYY-MM-DD>.md with Write. Otherwise print it.

Important Rules

1. Read-only against AWS. Only describe, list, get and log queries. Never modify a flow, bot, Lambda, alarm or table, never publish a bot version, never purchase anything and never write to the customer account.
2. Never modify flows or bots in the repo either. Report the fix; do not apply it. This skill produces findings, not diffs.
3. Evidence or it is not a finding. Every row cites a file and line, a flow block identifier, or a resource id. A concern without evidence goes into "What to test next", not into the table.
4. Never log real caller data into learnings. Phone numbers, names, transcripts and slot values seen during the review stay out of the learnings log and out of the report. Use placeholders.
5. German-market notes when the region is eu-*. Add DSGVO notes on transcript retention, log obfuscation, model region and session TTL. Do not add them for other regions.
6. Estimates are labelled. A latency or cost number you did not measure says "estimated" next to it.
7. Say what you could not check. If an input was missing or the CLI had no access, the row is N-A and goes under "Not checked" at the end of the report. Never let a failed call read as a clean result: capture the exit status of every aws call and every grep whose emptiness would otherwise be taken as evidence.

{{include lib/snippets/capture-learnings.md}}