congressional_trade_tracking v1.0.0

name: congressional_trade_tracking description: Reads US congressional stock disclosures as a research signal across all filers in both chambers: pulls Periodic Transaction Reports from the House Clerk and Senate eFD, parses each filing into normalized rows, computes disclosure lag against the 30 and 45 day STOCK Act rule, and reports clusters and activity with the limits stated plainly. Use when someone asks what members of Congress are trading, wants a filing season worked end to end, needs a PTR explained, or wants a tracker headline checked against the actual filing.

Congressional Trade Tracking

Purpose

Give an agent a complete, primary-source method for reading congressional securities disclosures. The data is public and free, but it arrives late, in dollar brackets, split across two chamber systems, and stripped of context by most trackers. This skill covers every filer in both chambers, ships a working parser and lag analyzer, and forces the reading to stay inside what a filing can actually support.

This is a research workflow. It produces an evidence-backed activity report. It never produces a trading recommendation.

Workflow

1. Scope the job before touching data

• State the question in one line: a filing season review, a ticker review, a member review, or a check on a specific tracker claim.
• Fix the window by transaction date and name the filing window that covers it. A season is a transaction-date window plus enough filing time after it for late reports to land. Say both windows in the report.
• Decide the filer set: all House, all Senate, one committee, or named members. All-filer is the default. A single-member read is a different, weaker product and must be labeled as such.

2. Pull House filings from the Clerk bulk index

• Download the yearly ZIP from the House Clerk: https://disclosures-clerk.house.gov/public_disc/financial-pdfs/<YEAR>FD.zip. Inside are a tab-separated index (<YEAR>FD.txt) and an XML index with the same fields.
• Parse the index and keep FilingType P rows. Those are the Periodic Transaction Reports. Other codes are annual, candidate, and other disclosure types, not trade reports.
• Run the bundled parser:
• python3 bin/ptr_tools.py index --download 2025 writes a CSV of PTR filings with filer, state and district, filing date, DocID, and the PDF URL for each filing.
• python3 bin/ptr_tools.py index <YEAR>FD.zip does the same from a local ZIP, .txt, or .xml index.
• Each House PTR PDF lives at https://disclosures-clerk.house.gov/public_disc/ptr-pdfs/<YEAR>/<DocID>.pdf. Open the PDF for every line you plan to report. The index tells you a filing exists; only the PDF tells you what is in it.
• The public search interface is at https://disclosures-clerk.house.gov/FinancialDisclosure for one-off lookups by name, state, district, year, and filing type.

3. Pull Senate filings from eFD

• Search the Senate Electronic Financial Disclosure database at https://efdsearch.senate.gov/search/. Accept the access agreement, then search by filer name, report type (Periodic Transaction Report), and date range.
• The Senate publishes no bulk ZIP like the House. Work report by report, save each report PDF or page, and transcribe its lines into the same normalized schema used for House rows. Record the Senate report identifier in the source field.
• Background on who files and where Senate reports go is on the Senate Public Disclosure page: https://www.senate.gov/legislative/Public_Disclosure/financial-disclosure.htm.

4. Parse each PTR into normalized rows

• Capture one row per transaction with these fields: filer, chamber, state or district, owner code, asset name as written, ticker if the filing or a verified lookup supplies one, transaction type, transaction date, notification date, filing date, amount low bound, amount high bound, the full description or comment text, and the source URL of the filing.
• Owner codes come from the form: blank is the filer, SP is spouse, DC is dependent child, JT is jointly held. Preserve the code. A spouse trade disclosed under a member's name is a household event, and reporting it as the member's own trade is an error.
• Transaction types: purchase, sale, sale with the partial sale flag, and exchange. Exchange has a narrow meaning on this form: old stock surrendered for new stock in a merger, acquisition, or spinoff.
• For options, the description should carry the underlying name, strike, expiry, and put or call. Copy the whole description into the row. If the description is missing or thin, mark the row as options detail unknown instead of guessing.
• Full field-by-field anatomy, the bracket table, and a worked due-date example are in references/ptr-anatomy.md.

5. Apply the amount brackets honestly

• Amounts are categories set in 5 U.S.C. section 13104(d)(1): $1,001 to $15,000, then $15,001 to $50,000, $50,001 to $100,000, $100,001 to $250,000, $250,001 to $500,000, $500,001 to $1,000,000, $1,000,001 to $5,000,000, $5,000,001 to $25,000,000, $25,000,001 to $50,000,000, and over $50,000,000.
• Store the low and high bound of the bracket, never a single invented amount.
• For season totals, report the sum of low bounds as the floor. A sum of midpoints may be used to rank tickers or filers, labeled as an estimate every time it appears. Count open-ended top-bracket rows separately, at their low bound, and say so.
• The reporting threshold is a gross transaction amount over $1,000. A sale that lost money still counts at its gross sale amount.

6. Compute lag and lateness the way the statute does

• Disclosure lag is filing date minus transaction date, in calendar days.
• The legal due date is the earlier of 30 days after the filer was notified of the transaction and 45 days after the transaction itself. That rule is in the STOCK Act amendment to the Ethics in Government Act, cited at 5 U.S.C. section 13105(l), and restated in the House Ethics instruction guide. No extensions are allowed for PTRs.
• A filing with a lag under 45 days can still be late if the filer was notified early. A filing with a lag over 45 days is late on its face. Judge lateness by the due date when the notification date is present, and say which test you used when it is missing.
• Run the analyzer on the normalized CSV: python3 bin/ptr_tools.py analyze examples/sample_transactions.csv prints lag distribution, filings late by the due-date rule, the owner split, amount floor and midpoint estimates, and purchase clusters as JSON.
• Report the lag distribution for the season in hand (minimum, median, maximum, count over 45 days). Do not import a median from a tracker or an article. Different corpora and windows give different numbers, and the season in hand is the only defensible source.
• Late filing carries a minimum $200 fee under the House guide, assessed after a 30-day grace period, and the ethics committee may waive it. A late filing is a compliance fact. It is not, by itself, evidence about why the trade happened.

7. Read the season with the lag in front of you

• Any follower return, price comparison, or "what happened next" check starts at the filing date, using the first close after the filing became public. Starting at the transaction date measures a return nobody outside the household could have acted on. If you show a transaction-date version at all, label it as a ceiling, not a result.
• Sort the narrative by transaction date and show the filing date and lag on every line. A report sorted by filing date alone makes old trades look current.
• Treat the disclosure as history with context value: who in the household traded, in what size bracket, how fast they disclosed, and whether the pattern repeats. The strongest honest claims are about behavior and clustering, not about future prices.
• Know the base rate before writing a verdict. A Chen and Sacerdote NBER working paper covering reported trades from 2012 through 2023 found that the average legislator trade roughly matched or slightly trailed broad market benchmarks, and that trades tended to follow public signals such as analyst revisions rather than lead them. Cite it as a working paper, note that it rests on self-reported filings and a low-bound assumption for brackets, and never use an average result to clear or accuse an individual filer.

8. Add spouse, account, and committee context with labels

• Spouse and dependent child rows: keep them in the dataset, report the owner split for the season, and analyze household patterns at household level. Do not attribute a spouse's trade to the member's direction without evidence outside the filing, and say plainly that the filing does not show who decided.
• Account context: read the description for managed account, brokerage, and retirement account notes. Many small trades on one date across many tickers from one filer usually means a manager rebalanced. The House guide confirms that reallocations inside managed, brokerage, and retirement accounts count as reportable purchases and sales.
• Committee context: pull current committee assignments from the official House and Senate member and committee pages, date them, and state the industry mapping you applied. Mark every committee overlap as analyst classification. Assignments change between and within Congresses, and a conglomerate ticker can sit under several committees at once.
• Cross-check holdings against the annual report (House Form A, due May 15 for the preceding calendar year; Senate annual reports are also due May 15). A PTR shows events. The annual report is what lets you say an asset appeared, grew, shrank, or disappeared year over year, within bracket precision.

9. Cluster before you conclude

• A cluster is 3 or more distinct filers buying the same ticker within 30 days by transaction date. The analyzer finds these with --window and --min-filers settings you can tighten or loosen, and the settings used must be printed in the report.
• Household rows count toward the filer who disclosed them, and the cluster table must show the owner codes inside the cluster. Three spouse accounts buying is a different observation from three members buying in their own names.
• Weigh a cluster by bracket size, by how many filers bought in larger brackets, and by whether sales in the same ticker appear in the same window. Report buys and sells side by side. A buy cluster with heavy selling next to it is a mixed picture, and the report must say mixed.
• Lone trades are activity, not signal. Report them in the table and keep them out of the verdict unless the same filer repeats the same ticker across filings.

10. Clear the false-positive list

• Work references/false-positives.md line by line before drafting. It covers spouse attribution, managed account rebalancing, fund lines that are not stock picks, dividend reinvestment, options flattened into stock trades, partial sales read as exits, merger and spinoff exchanges, ordinary-reason sales, amendments double-counted as new trades, old trades presented as new, bracket width mistaken for precision, and committee overlap asserted from a ticker alone.
• Know the statutory blind spots and name them in every season report: transactions at or under $1,000 are not reported; Excepted Investment Fund and mutual fund and ETF transactions are excluded from PTRs under the House guide; assets in qualified blind trusts and excepted trusts sit outside the PTR requirement; real property, certificates of deposit, cash account moves, stock splits, inheritances, and bond calls and maturities are excluded. Absence from the record never proves a household did not trade.

11. Work one filing season end to end

• Pull both chamber sets for the window, House by bulk index and Senate by eFD search, and log how many filings each chamber produced and how many you parsed.
• Normalize every line, dedupe amendments against originals, and run the analyzer.
• Hand-check a sample: reopen at least 10 percent of the PDFs behind the rows, or all of them if the season is small, and confirm owner, type, dates, bracket, and description match the normalized row.
• Draft the report in the Output Contract order, run the false-positive list against the draft, and cut any claim the filings do not support.
• State the coverage gaps in the report itself: Senate transcription limits, filings that arrived after your pull date, and any member whose annual report you could not cross-check.

Output Contract

A congressional trade report must contain:

• Scope: the question, transaction-date window, filing pull date, chambers and filer set covered, and counts of filings pulled and parsed per chamber.
• Transaction table: one row per transaction with filer, owner code, asset and ticker, type (with partial sale and options detail preserved), transaction date, notification date, filing date, lag in days, amount bracket as printed, and the filing source URL.
• Lag section: lag distribution for the set, the count late by the due-date rule, and the late lines named with their due dates.
• Amounts section: low-bound floor total, midpoint estimate labeled as an estimate if used, and the count of open-ended top-bracket rows.
• Owner and account section: the SP, DC, JT, and self split, plus any managed account or rebalancing patterns found, with the evidence for calling them that.
• Clusters: each cluster with ticker, distinct filers, owner codes, window, combined bracket floor, and the sales picture in the same ticker and window. Cluster settings printed.
• Committee context: overlaps stated as analyst classification, with assignment source and date.
• Verdict: a short paragraph that separates what the filings show, what they suggest, and what they cannot show. The limits from step 10 appear here in plain language.
• Sources: a link to the official filing behind every row or cluster claim. Tracker links may be added as finding aids and must be labeled as secondary.

Operating Rules

1. Primary sources only for facts: the House Clerk database and its bulk ZIP, Senate eFD, the House and Senate ethics instruction material, and the statute. Aggregators and trackers are leads for finding filings, never evidence for a claim.
2. Open the filing before reporting the trade. A tracker row is a summary that can drop the owner code, the options description, and the partial sale flag. If you cannot open the filing, mark the row unverified and keep it out of the verdict.
3. Never convert a bracket into an exact amount, a share count, or a position size. The form does not contain them.
4. Never measure a follower result from the transaction date. Public means filed. Anything earlier is a ceiling and must be labeled as one.
5. Never attribute motive. A filing shows that a trade happened, when, in what bracket, and in whose name in the household. It does not show why, and it does not show who decided for a spouse or dependent child.
6. Preserve owner, options, and partial sale detail through every step. Losing any of the three changes what the data says.
7. Dedupe amendments and re-pulls. The same trade counted twice is a fabricated cluster.
8. Date every committee assignment and label every industry mapping. Undated context rots silently and misleads the next reader.
9. This is research, not financial advice. Say so in the report when a reader could act on it. Do not frame any cluster, member, or ticker as a buy or sell recommendation.
10. If nothing in the season survives the filters, report that plainly. An empty or quiet season is a correct result, and padding it with weak rows is a failure of this skill.