# Feature Spec: Leadership / Committee Role Filters for U.S. Congress Directory

## Recommendation

Add this feature.

For national issues, contacting committee chairs, ranking members, and chamber leadership can be more impactful than contacting random members because these roles control hearings, agendas, and investigations. This should complement, not replace, contacting a user’s own representatives.

## Goal

Allow users to filter members by:

- chamber
- state
- district
- party
- leadership role
- committee
- committee role

## Scope

### In Scope

- Current Congress only
- Current House and Senate leadership roles
- Current committee chairs and ranking members
- Combined filtering with existing member filters
- Display official contact details on results

### Out of Scope

- Historical roles
- Influence scoring
- Issue recommendations
- Non-official contact info

## User Stories

- As a user, I can filter by `leadership_role`.
- As a user, I can filter by `committee` and `committee_role`.
- As a user, I can combine those filters with state, district, party, and chamber.
- As a user, I can view official contact details for matching members.

## Data Model

Copy

`type Member = {
  bioguideId: string
  congress: number
  chamber: 'house' | 'senate'
  fullName: string
  party: string
  state: string
  district?: string | null
  officePhone?: string | null
  contactFormUrl?: string | null
  leadershipRoles: LeadershipRole[]
  committeeRoles: CommitteeRole[]
}`

`type LeadershipRole = {
  roleType: LeadershipRoleType
  label: string
  isCurrent: boolean
}`

`type CommitteeRole = {
  committeeCode: string
  committeeName: string
  roleType: CommitteeRoleType
  isCurrent: boolean
}`

`type LeadershipRoleType =
| 'speaker'
| 'house_majority_leader'
| 'house_minority_leader'
| 'house_majority_whip'
| 'house_minority_whip'
| 'senate_majority_leader'
| 'senate_minority_leader'
| 'senate_majority_whip'
| 'senate_minority_whip'
| 'president_pro_tempore'`

`type CommitteeRoleType =
| 'chair'
| 'ranking_member'
| 'member'`

## Data Rules

- Store only roles for the current Congress.
- Normalize source values into canonical enums before saving.
- A member may have multiple roles.
- Committee role filters must support at least:
  - `chair`
  - `ranking_member`
  - `member`

## Data Sources

Use free official government sources:

- [House Clerk member data](https://clerk.house.gov/member_info/MemberData_UserGuide.pdf)
- [Senate XML availability](https://www.senate.gov/general/common/generic/XML_Availability.htm)
- [Senate current member XML](https://www.senate.gov/legislative/LIS_MEMBER/cvc_member_data.xml)
- [House leadership source](https://clerk.house.gov/Members/ViewLeadership)
- [Senate leadership source](https://www.senate.gov/senators/leadership.htm)
- [Congress.gov API](https://api.congress.gov/) as optional enrichment/fallback

## Backend Requirements

### Filters

Support:

Copy

`GET /members?party=Democrat
GET /members?leadership_role=house_minority_leader
GET /members?committee_role=ranking_member
GET /members?committee_code=HSJU&committee_role=ranking_member
GET /members?state=WA&party=Democrat&committee_role=chair`

### Behavior

- Filters use AND logic across categories.
- Results are paginated.
- Only current members and current roles are returned.
- If a member has multiple matching roles, return the member once.

## UI Requirements

### Filters

Add:

- Leadership Role dropdown
- Committee dropdown
- Committee Role dropdown

### Member Card

Show:

- name
- chamber
- party
- state / district
- office phone
- contact form link
- role badges, such as:
  - House Democratic Leader
  - Chair, Senate Judiciary
  - Ranking Member, House Oversight

## Acceptance Criteria

- User can filter by leadership role.
- User can filter by committee and committee role.
- User can combine new filters with state, district, party, and chamber.
- Chairs and ranking members are correctly identified.
- Only current Congress role data is shown.
- Official contact details appear on each result.
- Data refreshes on a scheduled sync and can be manually refreshed.

## Edge Cases

- Members with multiple committee roles
- Members with both leadership and committee roles
- Vacancies
- House members with no district value where applicable
- Missing role data from a source

## Implementation Order

1. Add role enums and schema changes
2. Ingest House roles
3. Ingest Senate roles
4. Add leadership ingest
5. Add API filters
6. Add UI filters and badges
7. Add tests

## Source Strategy

1. [House Clerk member data](https://clerk.house.gov/member_info/MemberData_UserGuide.pdf)
2. [Senate official XML](https://www.senate.gov/general/common/generic/XML_Availability.htm)
3. Official House and Senate leadership sources
4. [Congress.gov API](https://api.congress.gov/) only if needed for enrichment or fallback