Pular para conteúdo

Auditoria de prontidão — SotuHire v0.1

Escopo

Auditoria executada antes da implementação do SotuHire v0.1 — MVP Core, em 12 de junho de 2026.

Baseline antes das alterações

  • total de arquivos rastreados: 135;
  • total de arquivos Markdown rastreados: 69;
  • arquivos Markdown em docs/: 67;
  • Markdown vazio: 0;
  • Markdown abaixo de 25 linhas: somente CONTRIBUTING.md, com 24 linhas e conteúdo completo;
  • testes: 12 passed;
  • Ruff: 1 falha preexistente de ordenação de imports;
  • build MkDocs: não executado no baseline porque o CLI mkdocs não estava instalado no ambiente local.

Resultado final

  • total de arquivos rastreados: 152;
  • total de arquivos Markdown rastreados: 74;
  • arquivos Markdown em docs/: 71;
  • arquivos Markdown existentes reduzidos: 0;
  • docs fora da navegação MkDocs: 0;
  • alvos de links Markdown locais quebrados: 0;
  • arquivos Markdown abaixo de 25 linhas: somente CONTRIBUTING.md, já presente e completo;
  • Ruff check: passou;
  • Ruff format check: 61 arquivos formatados;
  • pytest: 39 passed;
  • MkDocs strict build: passou;
  • Streamlit headless health check: ok.

Docs presentes e integridade

Todos os documentos rastreados no início da auditoria continuam presentes. A baseline de linhas foi registrada antes das edições e será comparada ao final.

Regra aplicada:

Nenhum documento Markdown existente pode ter menos linhas ao final da implementação.

A verificação de links Markdown locais encontrou:

  • alvos locais quebrados: 0;
  • links internos com fragmentos: 0;
  • referências externas: mantidas para validação editorial posterior.

Status do README

Gap encontrado: o README continha a visão ampla, mas ainda descrevia a v0.1 antiga como PDF + LLM e indicava o projeto como preparação de MVP.

Correção: README alinhado ao MVP Core atual, com definição curta, features, arquitetura, stack, comandos, testes, Ruff, status, privacidade/compliance, benchmarks, docs principais e próximos passos.

Status do MkDocs

Gap encontrado: dois resumos históricos estavam fora da navegação:

  • 00-audit/expanded-update-summary.md;
  • 00-audit/mvp-tailor-fit-update-summary.md.

Correção: navegação ampliada para incluir auditorias históricas, esta auditoria, regras operacionais do Opportunity Fit, implementação v0.1 e metadados do repositório.

Cobertura de visão e roadmap

Os docs citam claramente:

  • Resume Tailor;
  • Opportunity Fit Score;
  • ATS Score;
  • JSON Resume / currículo mestre;
  • Gemini Structured Outputs + Pydantic;
  • RAG simples de carreira como futuro próximo;
  • GitHub/Portfolio Score;
  • LinkedIn/Profile Score;
  • Search Intelligence;
  • Hidden Jobs Radar;
  • Job Tracker/Kanban;
  • extensão assistiva futura;
  • Concurso Mode apenas como futuro experimental;
  • PyTorch/ML pesado fora do MVP.

Gaps encontrados

  • v0.1 inconsistente entre README e roadmap;
  • ausência de app.py;
  • ausência do analisador integrado;
  • ausência do módulo ATS;
  • ausência de utilitários centrais de texto;
  • nomes públicos pedidos ainda ausentes em algumas funções;
  • suíte de testes menor que os critérios de aceite;
  • dependências padrão mais pesadas que o MVP;
  • Ruff com uma falha de import;
  • docs importantes fora do MkDocs;
  • ausência de changelog e metadados recomendados.

Gaps corrigidos

  • README e roadmap alinhados ao SotuHire v0.1 — MVP Core;
  • app.py criado com interface Streamlit funcional;
  • analisador integrado criado em modules/analyzer/job_analyzer.py;
  • ATS Score simples criado em modules/ats/ats_score.py;
  • utilitários de texto criados em modules/core/text_utils.py;
  • funções públicas pedidas implementadas e testadas;
  • schemas Pydantic fortalecidos, incluindo bloqueio de invented_information=True;
  • suíte ampliada de 12 para 39 testes;
  • dependências padrão reduzidas ao necessário para a v0.1;
  • dependências futuras separadas em arquivos específicos;
  • falha inicial do Ruff corrigida e formatação aplicada;
  • todos os docs importantes incluídos no MkDocs;
  • changelog e metadados do repositório criados;
  • build MkDocs estrito validado;
  • startup Streamlit validado pelo endpoint de saúde.

Docs novos

  • CHANGELOG.md;
  • docs/00-audit/v0.1-readiness-audit.md;
  • docs/03-business-rules/opportunity-fit-rules.md;
  • docs/07-development/mvp-v0.1-implementation.md;
  • docs/07-development/repository-metadata.md.

Docs alterados

  • README.md;
  • docs/01-product/roadmap.md;
  • docs/01-product/mvp-scope.md;
  • docs/03-business-rules/resume-tailor-rules.md;
  • docs/03-business-rules/opportunity-fit-score.md;
  • docs/04-ai/gemini-structured-output.md;
  • docs/04-ai/json-resume-and-pydantic.md;
  • docs/07-development/mvp-core-implementation.md;
  • mkdocs.yml.

Confirmação de não redução

Comparação final executada contra origin/main:

REDUCED_EXISTING_MARKDOWN=0

Todos os documentos Markdown existentes continuam presentes. Nenhum documento existente teve redução no número de linhas.

Resultado final:

BROKEN_LINKS=0
DOCS_OUTSIDE_NAV=0
mkdocs build --strict: passed

Os dois resumos históricos que estavam fora da navegação foram adicionados, junto com os novos docs da v0.1.

Qualidade e execução

Comandos finais executados:

ruff format .
ruff check .
ruff format . --check
python -m pytest -q
mkdocs build --strict
streamlit run app.py --server.headless=true

Resultados:

  • Ruff check: passou;
  • Ruff format check: 61 arquivos já formatados;
  • Pytest: 39 passed;
  • MkDocs: documentação construída com modo estrito;
  • Streamlit: endpoint /_stcore/health retornou ok.

Próximos passos

  1. validar heurísticas com fixtures fictícias mais diversas;
  2. adicionar exemplos e screenshots da interface;
  3. integrar Gemini Structured Outputs como opção, mantendo fallback determinístico;
  4. evoluir para RAG simples de carreira com evidências rastreáveis;
  5. implementar Job Tracker/Kanban antes de automações de descoberta;
  6. manter Search Intelligence, Hidden Jobs Radar, scores de perfil e extensão assistiva fora do núcleo até a validação da v0.1.