mirror of https://github.com/NomaDamas/k-skill.git synced 2026-06-24 02:04:11 +00:00

Jeffrey (Dongkyu) Kim 19de41c166 Prevent filtered NEC lookup false negatives

Fix the candidate parser so documented education-superintendent and filtered local-election lookups return bounded, evidence-backed results instead of silently dropping valid rows.

Constraint: PR #266 round-3 review required TDD, Ralph verification, and branch update for issue #256.

Rejected: Full NEC pagination in this follow-up | broader than the approved change; bounded 100-row fetch now avoids user-limit false negatives and warns when capped.

Confidence: high

Scope-risk: narrow

Directive: Preserve exact-name fail-closed parsing and count raw parsed upstream rows before cap-warning decisions.

Tested: git diff --check; node --test packages/local-election-candidate-search/test/index.test.js; npm run lint --workspace local-election-candidate-search; npm run test --workspace local-election-candidate-search; npm pack --workspace local-election-candidate-search --dry-run; live CLI smokes for 오세훈, 조희연, 김동연; CLI help/no-args checks; architect verification CLEAR.

Not-tested: Full npm run ci remains blocked by pre-existing repo-wide missing SKILL.md: ohou-today-deal.

2026-05-18 16:54:50 +09:00

4 KiB

Raw Blame History

name

description

license

metadata

local-election-candidate-search

중앙선거관리위원회 선거통계시스템 공개 통합검색으로 한국 지방선거 후보자 정보를 이름/선거종류/지역 기준으로 조회한다.

MIT

category	locale	phase
civic	ko-KR	v1

Local Election Candidate Search

What this skill does

중앙선거관리위원회(NEC) 선거통계시스템의 공개 통합검색에서 후보자 이름을 조회하고, 지방선거 관련 후보자 이력만 기본으로 정리한다. 후보자명, 한자명, 생년월일/성별, 선거일, 선거명, 선거종류, 정당, 선거구, 득표, 직업, 학력, 경력 등을 반환한다.

When to use

사용자가 “지방선거 후보”, “시도지사 후보”, “기초의원 후보”, “교육감 후보” 등을 이름/지역/선거일 기준으로 찾아 달라고 할 때
중앙선관위 선거통계시스템에서 공개된 후보자 이력을 확인해야 할 때
동명이인이 있을 수 있어 후보자명 + 선거종류/지역/연도 필터가 필요한 때

Public access path

Chosen path: NEC integrated candidate search.

Entry page: https://info.nec.go.kr/search/searchCandidate.xhtml
Method: unauthenticated public POST
Required form field: searchKeyword=<정확한 후보자 성명>
Helper package: local-election-candidate-search

Why this path: the visible NEC UI explicitly exposes candidate-name integrated search across recent and historical elections, and it returns the candidate result cards in server-rendered HTML. It is more stable than scraping per-election menu pages because it does not require selecting every city/town/constituency combo first.

Workflow

Use the package CLI from this repository or installed workspace:

npx local-election-candidate-search 오세훈 --election 시도지사 --region 서울 --limit 5

Narrow ambiguous/homonym results:

npx local-election-candidate-search 김동연 --date 2014 --election 기초의원 --region 동작

Include non-local races only when the user asks for all NEC integrated-search matches:

npx local-election-candidate-search 이재명 --all --limit 20

Inputs

Candidate name: exact Korean name; required.
--election: one of 시도지사, 기초단체장, 광역의원, 기초의원, 광역비례, 기초비례, 교육감.
--date / --year: YYYY, YYYYMMDD, or YYYY.MM.DD.
--region: free text filter against parsed district/region text.
--limit: max rows, capped at 100.
--all: include non-local election results.

Outputs

Return concise JSON. Each items[] row may include:

name, hanja, birth_date, gender
election_date, election_name, election_code, election_type
party, district, votes, vote_share, elected
job, education, career[]
upstream code fields such as city_code, sgg_city_code, town_code

summary.upstream_result_limit shows the NEC row count requested before local client-side filters. Filtered searches request up to 100 upstream rows first, then apply exact-name matching, local/election/date/region filters, deduplication, and the final --limit.

Failure modes

no candidate results: NEC returned no matching card or filters removed all matches.
unexpected NEC search HTML: upstream may be in maintenance, NetFunnel queue, login/blocked state, or markup changed.
NEC search page was capped: filtered results are based on the maximum fetched page and may require upstream pagination for exhaustive coverage.
Homonyms: the same name can appear across many elections; always show election date/type/district and apply user-provided filters.
Future elections: candidate registration data may be incomplete until NEC publishes it.

Done when

Results are sourced from info.nec.go.kr public HTML.
Local-election filtering is applied unless the user requested --all.
Any warnings/failure modes are shown instead of silently claiming no results.

4 KiB Raw Blame History