Kanchi Dividend Review Monitor

# Kanchi Dividend Review Monitor

## Overview

Detect abnormal dividend-risk signals and route them into a human review queue.
Treat automation as anomaly detection, not automated trade execution.

## When to Use

Use this skill when the user needs:
- Daily/weekly/quarterly anomaly detection for dividend holdings.
- Forced review queueing for T1-T5 risk triggers.
- 8-K/governance keyword scans tied to portfolio tickers.
- Deterministic `OK/WARN/REVIEW` output before manual decision making.

## Prerequisites

Provide normalized input JSON that follows:
- `references/input-schema.md`

If upstream data is unavailable, provide at least:
- `ticker`
- `instrument_type`
- `dividend.latest_regular`
- `dividend.prior_regular`

## Non-Negotiable Rule

Never auto-sell based only on machine triggers.
Always create `WARN` or `REVIEW` evidence for human confirmation first.

## State Machine

- `OK`: no action.
- `WARN`: add to next check cycle and pause optional adds.
- `REVIEW`: immediate human review ticket + pause adds.

Use `references/trigger-matrix.md` for trigger thresholds and actions.

### Flat-dividend cadence caveat

When T6 is driven only by `freeze_flag` / latest regular dividend equal to prior regular dividend, treat it as a `WARN` for cadence confirmation, not as proof of dividend deterioration. Many quarterly dividend payers repeat the same dividend for several quarters between annual raise cycles. In reports, phrase this as “confirm next dividend-growth cadence / pause optional adds until checked” and avoid implying a cut or broken thesis unless T1/T2/T3/T4/T5 evidence also supports escalation.

## Monitoring Cadence

- Daily:
  - T1 dividend cut/suspension.
  - T4 SEC filing keyword scan (8-K oriented).
- Weekly:
  - T3 proxy credit stress checks.
- Quarterly:
  - T2 coverage deterioration and T5 structural decline scoring.

## Workflow

### 1) Normalize input dataset

Collect per ticker fields in one JSON document:
- Dividend points (latest regular, prior regular, missing/zero flag).
- Coverage fields (FCF or FFO or NII, dividends paid, ratio history).
- Balance-sheet trend fields (net debt, interest coverage, buybacks/dividends).
- Filing text snippets (especially recent 8-K or equivalent alert text).
- Operations trend fields (revenue CAGR, margin trend, guidance trend).

Use `references/input-schema.md` for field definitions
and sample payload.

### 2) Run the rule engine

Run:

```bash
python3 skills/kanchi-dividend-review-monitor/scripts/build_review_queue.py \
  --input /path/to/monitor_input.json \
  --output-dir reports/
```

The script maps each ticker to `OK/WARN/REVIEW` based on T1-T5.
Output files are saved to the specified directory with dated filenames (e.g., `review_queue_20260227.json` and `.md`).

### 3) Prioritize and deduplicate

If multiple triggers fire:
- Keep all findings for audit trail.
- Escalate final state to highest severity only.
- Store trigger reasons as single-line evidence.

### 4) Generate human review tickets

For each `REVIEW` ticker, include:
- Trigger IDs and evidence.
- Suspected failure mode.
- Required manual checks for next decision.

Use `references/review-ticket-template.md` output format.

## SEC Filing Guardrail

When implementing live SEC fetchers:
- Include a compliant `User-Agent` string (name + email).
- Use caching and throttling.
- Respect SEC fair-access guidance.
- In scheduled portfolio reviews where upstream filing snippets are empty, use SEC `company_tickers.json` plus `https://data.sec.gov/submissions/CIK##########.json` to enumerate recent 8-K / 8-K/A filings for each holding, then scan primary filing documents for the T4 keyword family (`Item 4.02`, non-reliance, restatement, material weakness, SEC investigation, subpoena, going concern, auditor resignation, internal control). Record the scan window, recent 8-K count, and whether hits were found. Treat "no keyword hits" as a narrow T4 scan result, not a full governance clearance.

## Output Contract

Always return:
1. Queue JSON with summary counts and ticker-level findings.
2. Markdown dashboard for quick triage.
3. List of immediate `REVIEW` tickets.

## Multi-Skill Handoff

- Consume ticker universe and baseline assumptions from `kanchi-dividend-sop`.
- Feed `REVIEW` results back to `kanchi-dividend-sop` for re-underwriting and position-size review.
- Share account-type context with `kanchi-dividend-us-tax-accounting` when risk events imply account relocation decisions.

## Resources

- `scripts/build_review_queue.py`: local rule engine for T1-T5.
- `scripts/tests/test_build_review_queue.py`: unit tests for T1-T5 and report rendering.
- `references/trigger-matrix.md`: trigger definitions, cadence, and actions.
- `references/input-schema.md`: normalized input schema and sample JSON.
- `references/review-ticket-template.md`: standardized manual-review ticket layout.